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PREFACE 



Intended mainly for the programmer cod- 
ing in assembler language, this book 
describes how to use the services of the 
supervisor, the macro instructions used to 
request these services, and the linkage 
conventions used by the control program to 
provide these services. 



This book is divided into two parts. 
Part I, "Supervisor Services", provides 

explanations and aids for using the facili- 
ties available through the supervisor by 
means of the macro instructions described 
in Part II, "Macro Instructions". 

Part I is divided into seven topics. 
Specific topics include: 

Program Design : Well designed programs 
use system resources efficiently. Know- 
ing the conventions and characteristics 
of the supervisor will help you design 
more efficient programs. 

Subtask Creation and Control ; Occasion- 
ally, you can have your program executed 
faster and more efficiently by dividing 
parts of it into subtasks that compete 
with each other and with other tasks for 
execution time. 

Program Management ; The supervisor can 
be used to aid communication between 
segments of a program. Save area, 
addressability, and passage of control 
from one segment of a program to another 
are discussed. 

Resource Control ; Portions of some 
tasks are dependent on the completion of 
events in other tasks. This requires 
planned task synchronization- Planning 
is also required when more than one pro- 
gram will be using a serially reusable 
resource. 

Interruption, Termination, and Dumping 
Services ; The supervisor provides faci- 
lities for writing exit routines to 
handle specific types of interruptions. 
It is not likely, however, that you will 
be able to write routines to handle all 
types of abnormal conditions. The 
supervisor therefore provides for ter- 
mination of your program when you requ- 
est it by issuing an ABEND iracrc 
instruction, or when the control prograir 
detects a condition that will degrade 
the system or destroy data. 



Virtual Storage Management : While vir- 
tual storage allows you to write large 
programs without the need for complex 
overlay structures, virtual storage roust 
be obtained for your iob step. Virtual 
storage is allocated by both explicit 
and iirplicit requests. 



Miscellaneous Services : In addition to 
the services outlined above, facilities 
are provided for timing events, extended 
precision floating-point simulation, 
operator coirmunicaticn with both the 
systeir and application programs, and 
tracing of data originating in applica- 
tion programs. 

Part II contains the descriptions and 
definitions of the supervisor iracrc 
instructions available in the OS/VS 
Asseirbler Language. It provides applica- 
tions prograirmers coding the assembler lan- 
guage with the information necessary to 
code the macro instructions. The standard 
list, and execute forms of the macro 
instructions are grouped, where applicable, 
for ease of reference. 

Use of this book requires a basic know- 
ledge of the operating system and of OS/VS 
assembler language. Books that contain 
inf-^rmation about these subjects are: 

OS/VSl Planning and Use Guide , GC24-5090 

OS/VS 2 Planning and Use Guide . GC28-0600 

OS/VS Assembler Language , GC33-U010 

When other IBM manuals are referred to 
in the text, only partial titles are given. 
The following is a list of the complete 
titles and order numbers of all manuals 
refeirred to in this book. 

OS/VS 

Checkpoint/Restart , GC26-378U 

Data Management Macro Instructions . 

GC26-3793 

Data Management Services , GC26-3783 
JCI Reference , GC28-670a 
linkage Editor and Loader , GC28-6451 
Service Aids , GC28-0633 

OS/VSl 

Debugging Guide , GC28-6670 

IBM Svstem/370 

Principles of Operation , GA22-7000 
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CHAPTER 1: INTRODUCTION TO SUPERVISOR SERVICES 



SUMMARY OF SERVICES 

The supervisor provides the resources that your programs need while 
assuring that as many of these resources as possible are being used at a 
given time. Well designed programs use system resources efficiently. 
Knowing the conventions and characteristics of the VS supervisor will 
help you design more efficient programs. 

The services you can request from the supervisor can be classified as 
follows: 



Subtask Creation and Control : Occasionally, you can have your program 
executed faster and more efficiently by dividing parts of it into sub- 
tasks that compete with each other and with other tasks for execution 
time. 



Program Management : The supervisor can be used to aid communication 
between segments of a program. Save areas, addressability, and passage 
of control from one segment of a program to another are discussed. 



Resource Control : Portions of some tasks are dependent on the comple- 
tion of events in other tasks. This requires planned task synchroniza- 
tion. Planning is also required when more than one program will be 
using a serially reusable resource. 

Interruption, Termination, and Dumping : The supervisor provides facili- 
ties for writing exit routines to handle specific types of interrup- 
tions. It is not likely, however, that you will be able to write rou- 
tines to handle all types of abnormal conditions. The supervisor there- 
fore provides for termination of your program when you request it by 
issuing an ABEND macro instruction, or when the control program detects 
a condition that will degrade the system or destroy data. 

Virtual Storage Management : While virtual storage allows you to write 
large programs without the need for complex overlay structures, virtual 
storage must be obtained for your job step. Virtual storage is allo- 
cated by both explicit and implicit requests. 

In addition to the services outlined above, the supervisor provides 
the facilities for timing events, extended precision floating-point 
simulation, operator communication with both the system and application 
programs, and tracing of data originating in application programs. 



CHARACTERISTICS OF THE SYSTEM 

Figure 1 gives a brief description of the control program options 
available for the operating systems that provide multiprogramming with 
virtual storage (OS/VSl and 0S/VS2). This figure does not attempt to 
cover all pf the options available in the operating system; it only sum- 
marizes th^ options that affect the material covered in this book. 
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Figure 1. Summary of characteristics and available options 
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CHAPTER 2; PROGRAM DESIGN 



All programs, regardless of function or relative position in the 
task, should be designed using certain conventions and with certain 
characteristics of the control progrcun in mind. This chapter describes 
these conventions and characteristics and discusses the effects they may 
have on the execution of your program. 



LINKAGE CONVENTIONS 

During the execution of a program, the services of another program 
may be required. The program that requests the services of another pro- 
gram is known as a calling program, and the program that was requested 
is known as the called program. For example* when the control program 
passes control to program A, program A becomes a called program. If 
program A in turn passes control to prcgrait B, program A becomes a cal- 
ling program, and program B becomes a called program. From the point of 
view of the control program, however, program A remains a called program 
until control is returned by program A. For more information on this 
subject, see the discussion under the heading "Task and Subtask Communi- 
cations" in "Chapter 3: Subtask Creation and Control." 

The following conventions are presented assuming one calling and one 
called program. They apply, however, to all called and calling programs 
operating in the system. If the conventions presented here are always 
followed, execution of the called program will not be affected by the 
method used to pass control or by the identity of the calling program - 



Linkage Registers 

Registers 0, 1, 13, 14, and 15 are known as the linkage registers ; 
they are used in fixed ways by the control program. It is good practice 
to use these registers in the same way in your program, since they may 
be modified by the control program or by your program when system macro 
instructions are used. Registers 2-12 are not changed by the control 
program. 

Registers 0 and 1 are used to pass parameters to the control program 
or to a called program. The expansions of some system macro instruc- 
tions result in instructions that load a value into register 0 or 1 or 
both, or load the address of a parameter list into register 1. For oth- 
er macro instructions, the control program uses register 1 to pass spe- 
cified parameters to the program you call. 

Register 13 contains the address of the save area provided by the 
calling program. 

Register 14 contains the return address of the calling program or an 
address within the control program to which your program is to return 
control when it has completed execution. 

Register 15 contains the entry address when control is passed to your 
program by the control program. The entry address of the called routine 
should be in register 15 when you pass control to another program. The 
expansion of some macro instructions results in instructions that load 
into register 15 the address of a parameter list to be passed to the 
control prc^graro. Register 15 is also used by the called program to 
return a v^lue (a return code) to the calling program. 



Chapter 2: Program Design 3 



The manner in which the control program passes the information in the 
FARM field of your EXEC statement is a good example of how th4 control 
program uses a parameter register to pass information. When (Control is 
passed to your program from the control program, register 1 contains the 
address of a fullword on a fullword boundary in your area of virtual 
storage (refer to Figure 2). The high^order bit (bit 0) of this word is 
set to 1. This is a convention used by the control program to indicate 
the last word in a variable-length parameter list; you must use the same 
convention when making requests to the control program. The low-order 
three bytes of the fullword. contain the address of a two-byte length 
field On a half word boundary. The length field contains a binary count 
of the number of bytes in the FARM field, which ironiediately follows the 
length field. If the FARM field was omitted in the EXEC statement, the 
cOunt is set to zero. To prevent possible errors, the count should 
always be used as a length attribute in acquiring the information in the 
FARM field. If your program is not going to use this information imme- 
diately, you should load the address from register 1 into one of regis- 
teris 2-12 or store the address in a fullword in your program. 



Saving the Calling Frograro's Registers 

The first action a called program should take is to save the contents 
of the calling program's registers. The contents of any register the 
called program modifies and the contents of the linkage registers must 
be saved. All registers should be saved to avoid errors when the called 
program is modified. 



The registers are saved in the 18-wcrd save area provided by the cal- 
ling program and pointed to by register 13. The format of this area is 
shown in Figure 3. As indicated by this figure, the contents of each 
register must be saved in a specific location within the save area. 
Registers can be saved either with a store-multiple (STM) instruction or 
with the SAVE macro instruction. The store-multiple instruction 



places the contents of all registers except 13 in the proper words of 
the save area. Saving register 13 is discussed under the heading "Pro- 
viding a Save Area.* 



STM 14^12,12(13) 



Register 
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Figure 2. Acquiring FARM field information 
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Figure 3. Format of the save area 


(A) 


PROGNAME 


SAVE (lU, 12) 


1 
1 
1 


(B) 


PROGNAME 


SAVE(5,10),T 



Figure 4. SAVE macro instruction used to save (A) all registers but 13 
and (B) registers 5-10, lH and 15 



The SAVE macro instruction generates instructions that store a desig- 
nated group of registers in the save area. The registers to be saved 
are coded in the same order as in an SIM instruction. Figure 4 illus- 
trates uses of the SAVE macro instruction. The T operand (in B) speci- 
fies that the contents of registers 14 and 15 are to he saved. 

The SAVE macro instruction or the equivalent instructions should be 
placed at the entry point to the program. 

Establishing a Base Register 

In System/370, addresses are resolved by adding a displacement to a 
base addresis. You must, therefore, establish a base register using one 
of the registers from 2-12 or register 15. If your program does not use 
V, system macro instructions and does not pasg control to another program. 
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a base register can be established using the entry address in register 
15. Otherwise, because both your prograni and the control program use 
register 15 for other purposes, you must establish a base using one of 
the registers 2-12. This should be done iirmediately after saving the 
calling program's registers. 

Providing a Save Area 

If any control section in your program passes control to another con- 
trol section, your program must provide its own save area. You must 
also provide a save area when you use certain system functions^ such as 
GET or PUT. If you establish which registers are available to the 
called program or control section, a save area is not necessary. Omit- 
ting the save area is not a good coding practice, however, since any 
changes in your program might necessitate changing a called program. 

Whether or not your progreun provides a save area, the address of the 
calling program's save area that you used must be saved, because you 
will need it to restore the registers before you return control to the 
program that called you. If you are net providing a save area, you can 
keep the address in register 13 or store it in a location in virtual 
storage. If you are creating your own save area, the following proce- 
dure should be followed: 

• Store the address of the save area that you used (the address passed 
to you in register 13) in the second word of the save area you 
created. 

• store the address of your save area (the address you will pass in 
register 13) in the third word of the calling program's save area. 

This procedure enables you to find the save area when you need it to 
restore the registers, and it enables a trace from save area to save 
area should one be necessary during a dump. 

Figures 5 and 6 show two methods of obtaining a save area and of sav- 
ing all the registers, including the addresses of the two save areas. 
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5. Chaining save areas in a nonreenterable program 
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Figure 6. Chaining save areas in a reenterable program 
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In Figure 5 the registers are stored in the save area provided by the 
calling program by using the STM instruction. Register 12 is then esta- 
blished as the base register. The address of the caller's save area is 
then saved in the second word of the new save area, established by the 
DC instruction. The address of the calling prograir's save area is 
loaded into register 2. The address of the new save area is loaded into 
register 13, and then stored in the third word of the caller's save 
area . 



In Figure 6, the SAVE macro instruction is used to store registers 
(an STM instruction could have been used) . The entry address is loaded 
into register 12, which is established as the base register. An uncon- 
ditional GETMAIN macro instruction (discussed in detail under the head- 
ing "Virtual Storage Management**) is issued requesting the control pro- 
gram to allocate 72 bytes of virtual storage from an area outside your 
program, and to return the address of the area in register 1- The 
addresses of the old and new save areas are stored in the assigned loca- 
tions, and the address of the new save area is loaded into register 13. 



Summary of Conventions to be Followed When Passing and Receiving Control 

The following is a list of conventions to be followed when passing 
and receiving control. The actual methods of passing control are 
described under the heading "Program Management." 

By a Called Program upon Receiving Control; 

• Save the contents of registers 0-12, IH, and 15 in the save area 
provided by the calling program. 

• Establish a base register. 

• Request the control program to allocate storage for a save area if 
you did not already allocate it by using a DC instruction. 

• Store the save area addresses in the assigned locations. 
By a Calling Program before Passing Control (Return Required) : 

• Place the address of your save area in register 13 . 

• Place the address at which you wish to regain control (the return 
address) in register lU. 

• Place the entry address of the program you are calling in register 
15. 

• Place the address of the parameter list (if there is one) in regist- 
er 1. (Passing parameters is discussed under "Program Management.") 

By a calling Program before Passing Control (No Return Required) : 

• Restore registers 2-12 and lU. 

• Place the address of the save area provided by the program that 
called you in register 13. 

• Place the entry address of the program you are calling in register 



• Place ^he addresses of parameter lists in registers 1 and 0. 
By a Called Program before Returning Control: 
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•Restore registers 0-12 and lU* 

• Place the address of the save area provided by the program you are 
returning control to in register 13. 

•Place a return code in the low-order tyte of register 15 if one is 
required. Otherwise, place the entry address of your program in 
register 15. 



VIRTUAI. STORAGE CONSIDERATIONS 

In a system with virtual storage you can distinguish between the 
address space used by a program (the program length) and the allocated 
real storage used for program execution. Real storage is allocated by 
the control program to meet realtime requirements. To use virtual 
storage effectively, you should consider the short-term demands on real 
storage and the time spent in allocating real storage (paging) . 

Paging 

Virtual storage is sequentially addressed, beginning with location 
zero, and is mapped into real storage as it is referenced. The size of 
virtual storage is limited only by the addressing capability of the sys- 
tem, and the amount of auxiliary storage. Virtual storage is divided 
into a maximum of 256 segments. In VSl, each segment is further divided 
into 32 pages, each containing 2,048 bytes (2K) of addressable space. 
In VS2, each segment is divided into 16 pages, each containing 1,096 
bytes (4K) of addressable space. 

The user and system are limited to a virtual storage capacity that is 
somewhat less than the 16 million bytes addressable with the 2U-bit 
addressing method used by System/370. The limits are determined by the 
installation on the basis of such factors as real storage capacity, 
secondary storage capacity, and control program storage requirements. 
The control program controls both real and virtual storage. A page is 
the smallest unit of real storage that can be allocated. The process by 
which pages are transferred between real and external page storage is 
called paging . 

An allocated virtual-storage page is always in one of three states: 
its content is on external page storage, its content is mapped into real 
storage, or it has no content and exists as address space only. Each 
time a page that is not in real storage is referred to, it must be paged 
into real storage. 

The control program coordinates paging with the execution of other 
tasks. As paging time increases, system efficiency decreases. Since 
paging time is attributable in part to the way in which a task uses vir- 
tual storage, the programmer should consider paging when he designs a 
program. 

Design Techniques 

A task's paging rate is a principal factor in determining how effi- 
ciently the task is executed. The following techniques for designing a 
program will help minimize paging and thus help ensure more efficient 
operation. 

• Code in page sections. It is useful to think of virtual storage as 
a "one-page overlay"; that is, only one page of virtual storage can 
be referred to without causing paging to occur. 

• Keep seldom used subroutines, such as initialization and termination 
subroutines, separate from those which are used frequently. You can 
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release whole pages of virtual storage associated with subroutines 
that are used only once. See "Relinquishing Virtual Storage" for 
details. 



Put frequently used subroutines in one page, preferably the page 
containing the most frequent callers. Similarly, group infrequently 
used or error routines together. 

Arrange data areas in a single page where possible. Avoid multiple- 
page lists and tables. 

Release pages for buffers as soon as they are all used. 

Keep frequently used programs or loops within programs in one page 
wherever possible. 

Keep dynamically changeable code in one page if possible. If a page 
has been changed it must be paged out before the real storage it 
occupies can be reused. Otherwise, the contents of the page can be 
overlaid. 

Arrange routines so that you avoid crossing page boundaries. 
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One cafjk is created by the control program as a result of initiating 
ex»;cution of the job rjtep (the job step task). You can create addition- 
al tasks in your program. If you do net, however, the job step task is 
the only task in a job being executed. The benefits of a multiprograin- 
ming en vironnient are still available even with only one task in the job 
Step; work is still being performed for other jpbs when your task is 
waiting for an event, such as an input operation, to occur. 

Tlie advantage in creating additional tasks within the job step is 

that ificie tasks are coirpeting for control than the task in the job you 
are concerned with. When a wait condition occurs in one of your tasks, 
it; is not necessarily a task from some other job that gets control; it 
way be one of your tasks, a portion of your jofc. 

The general rule is that parallel execution of a job step (that is, 
more than one task in a job step) should be chosen only when a signifi- 
cant amount of overlap between two or nore tasks can be achieved. The 
ciBftount of time taken by the control program in establishing and control- 
ling additional tasks, and your increased effort to coordinate the tasks 
and provide for conimuni cat ions between their roust be taken into account. 



C ltEj^TING THE TASK 

A new task is created by issuing an ATTACH macro instruction. The 
task that is active when the ATTACH macro instruction is issued is the 
originating task; the newly created task is the subtask of the originat- 
ing task. The subtask competes for control in the same manner as any 
other task in the system, on the basis of priority and the current abi- 
lity to use the central processing unit. The address of the task con- 
trol block for the subtask is returned in register 1. 

It the ATTACH macro instruction is executed successfully, control is 
returned to the user with a hexadecimal code of '00' in register 15. 

The entry point in the load module to be given control when the sub- 
i:ack becomes active is specified as it is in a LINK macro instruction, 
that is, through the use of the EP, EPLOC, DE, and DCB operands. The 
'fcie of these operands is discussed in "Program Management." Parameters 
can be passed to the subtask using the PARAM and VL operands, also 
described under "The LINK Macro Instruction." The only additional 
operands are those dealing with the priority of the subtask and the 
operands that provide for communication between tasks. 

CAOT^^ All modules contained in the libraries for a job step should 

he uniquely named. If duplicate module names are contained in these 
libraries, the results are unpredictable. 



T/i3K PRIORITY 

Tasks compete tor control on the basis of priority. When a task is 
created, it is assigned a priority, which can fce revised upward or down^ 

v;ard. It is also assigned a limit to its priority, a value equal to the 
highest priority the task can be assigned; this value is called the 
task's limi t p rior ity . The task's actual priority, the basis on which 
it competes for control, is called the task's dispatching priority . 



10 



A job step task can change its own (lispatchinfi j;' i^^'^i^^y t)Ut not:. iVij 
own limit priority . It can change both the dispatching and liiri t 
priorities of its subtasks, but cannot set tht; lii.dt priority of o. .yub- 
task higher than its own limit priority- 

Priority of the Jo b Step Tas k 

The limit priority of the job step task cannot be changed; it is 
always equal to the task's initial dispatching priority. You can specv 
fy initial dispatching priority through the DFPTY parameter of IIk? L'XEC 
statement. 

The initial dispatching priority of the job step task is determined 
by the job priority. You either specify jet priority through the PRTY 
parameter of the JOB stateirent or omit this parameter and allow the job 
priority to be determined by default. Job priority is used in selectiiiv? 
jobs for execution and in assigning input/output devices. 

To specify job priority, code the parameter: PRTY=value 

where value is the job priority, an integer from 0 to 13. If you do not. 
specify dispatching priority for a job step, it ifi computed from the job 
priority as follows: 

Dispatching Priority = (value x 16) <^ 11 

Whether you specify dispatching priority or not, you cannot be abso- 
lutely certain of what a job step's initial dispatching priority will 
be. To achieve best results from the operating system, the operations 
staff may override specified job and dispatching priorities. Your pro- 
gram, therefore, cannot simply assume that the job step task will have a 
particular initial dispatching priority. To deteririne this priority, 
your program must issue the EXTRACT macro instruction, as described in 
the VSl Planning and Use Guid e and VS2 Superv isor Se rvi ces an d Mac ro 
Instructions for the System Programmer. 

To summarize, the initial dispatching priority of the job step tank 
can be established three ways: 

• Indirectly through the PRTY parameter of the JOB statement 

• By default when the PRTY parameter is omitted 

• By the operations staff, overriding your own specifications 

Whichever way it is established, the initial dispatching priority ia 
always the limit priority for the job step task. 

The job step task can lower its dispatching priority by use of the 
GHAP macro instruction. It can later use this macro instruction to 
revise its dispatching priority either upward or downward. It can never 
raise its dispatching priority above its initial dispatching (lijiiit) 
priority . 

Priority of Sub tasks 

When a subtask is created, the limit and dispatching priorities of 
the subtask are the same as the current limit and dispatching priorities 
of the originating task except when the subtask priorities are modified 
by the LPMOD and DPMOD operands of the ATTACH iracrc instruction, Tho 
LPMOD operand specifies the number to he subtracted from the current 
limit priority of the originating task. The result of the subtraction 
is assigned as the limit priority of the subtask. If the result is zero 
or negative, zero is assigned as the limit priority. The DPMOD operand 
specifies the number to be added to the current dispatching priority of 
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the originating task. The result of the addition is assigned as the 
dispatching priority of the subtask, unless the nuwber is greater than 
the limit priority. In th^t cas6> the limit priority is used as the 
dispatching priority. 

Assigning and Chanqinq Priority 

Tasks with a large number of input/output operations should be 
as^iigned a higher priority than ta&ks with little input/output, because 
the tasks with imch input/outp«tt will be in a wait condition for a 
greater amount of time. The lower priority tasks will be executed when 
the higher priority tasks are in a wait condition. As the input/output 
operations are completed, the higher priority tasks get control, so that 
more I/O can be started. 

If one or more subtasks must be completed before the originating task 
can execute beyond a certain point, the subtasks that must be completed 
should be assigned a priority that will prevent a long wait in the ori- 
ginating task. 

Since tasks from other job steps are competing for CPU time, the 
priority initially established for the subtasks may be too high or too 
low to properly execute the job step. To correct this, the priorities 
of these subtasks can be changed by using the CHAP macro instruction. 
The EXTRACT macro instruction can be used to determine the priority of 
the current task and its subtasks. Note that each change of 16 in limit 
or dispatching priority is equivalent to a change of one in job 
priority. 

The CHAP macro instruction changes the dispatching priority of the 
active task or one of its subtasks. By adding a positive or negative 
value, the dispatching priority of the active task or a subtask is 
changed. The dispatching priority of the active task can be made less 
than the dispatching priority of another task waiting for control. If 
this occurs, the waiting task would be given control after execution of 
the CHAP macro instruction. 

The CHAP macro instruction can also be used to increase the limit 
priority of any of the active task's subtasks- The active task cannot 
change its own limit priority. The dispatching priority of a subtask 
can be raised above its own limit priority, but not above the limit of 
the originating task. When the dispatching priority of a subtask is 
raised above its own limit priority, the subtask* s limit priority is 
automatically raised to equal its new dispatching priority. 



DYNAMIC DISPATCHING (VSl) 

Dynamic dispatching is an optional Eeaturei of the operating system 
which provides for the alteration of th4 dispatching priorities of 
selected tasks as they are being executed. 

A dynamic dispatching algorithm calculates dispatching priorities so 
ta^ks can use system resources more efficiently. The algorithm not only 
alters the handling of each task as the task's characteristics change, 
but the algorithm also evaluates itself and alters itself, based on its 
effectiveness in handling the tasks under its con^ 

This algorithm distinguishes between I/G-bound tasks and CPU-bound 
tasks; I/O-bound tasks receive the higher priority. Initially, all 
tasks are designated I/O-bound; any new tasks entering the dynamically 
dispatched group are also designated I/O- laoa^ As each task is dis- 
pa1:chedr its aotivity is itionitorect fo^c St predetermined time interval. 
At the end of tkis time interval fea<?h task is designated l/o-bound or 
CPU-bound. 
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queue from old location of 

task 


I/O 


Preeitiption for 
Another Task 


Unchanged 


Dispatch preempting task 


CPU 


Voluntary 
Surrender 
and no 
Intervd 1 
Expiration 


I/O 


Nove task to bottom of I/O 
subgroup and search down 
CPU-queue from old location 
of task 


CPU 


Time Interval 
Ended 


Unchanged 


Move task to bottom of CPU 
subgroup and search down CPU- 
queue from old location of 
task 


CPU 


Preemption for 
Another Task 


Unchanged 


Move task to bottom of CPU 
subgroup and dispatch pre- 
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Figure 6A. Status change as a result of loss of CPU control 



Dynamic dispatching assumes that the task most likely to be I/O-bound 
the next time it is dispatched is the task that was I/O-bound the last 
time it was dispatched. 

Each time a task in the dynamically dispatched group relinquishes 
control of the CPU, its relative position within the task queue may 
change as shown in Figure 6A. 

I/O-bound tasks that remain I/O-bound tend to migrate higher in the 
queue as other I/O-bound tasks change status and join the CPU-bound task 
queue. A task that changes from I/O-bound to CPU-bound receives the 
highest dispatching priority within the CPU-bound group. In contrast, a 
CPU-bound task that switches to the I/O-bound group has the lowest 
priority within the I/O-bound group. This mechanism aids in making a 
finer distinction between tasks with relatively constant I/O activity 
and those tasks characterized by many status changes. 

The cyclic movement of the CPU-bound tasks ensures that they will all 
share in any available CPU time. Therefore, these tasks have increased 
chances to change their status; potential I/O tasks are not locked in at 
the bottom of the CPU- bound queue. 



Note: CPU-bound tasks that voluntarily surrender control of the CPU are 
examined between wait states. If the task's time interval expires, a 
bit is posted in the task's TCB to indicate the expiration. When the 
task issues a WAIT, this bit in the TCB is checked. If the time interv- 
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al has expired, -fehe bit is reset , an^ the status of the task remains 
(GPU-^bound. 

if the time interval has not eaepired simce the previous WAltP, the 
Statiis of the task is changed to lli^O^aDOuiid. 

The user iftust specify the desired ratio of CPU-bound tasks to I/O- 
boiMd tasks. The algorithifi cheeks this ratio, and when there are too 
aiai^ GPO-bound tasks in the systero, the time interval is lengthened- if 
therfe are too mahy 1/0-bound taslcs ih the systrein, the time interval is 
d'ecreased-. 

'DynairoiG dispatching is a SYSGEN option. The CTFLPROG macro will have 
jparameters for specifying the following information to the control 
program. 

• J'irst and last partitions in the dynamic dispatching group (parti- 
tions must be contiguous) . There is no default value for this 
parameter. 

• Desired ratio of CPU-bound tasks to I/O-bound tasks. This value is 
specified in hundredths (for example, a ratio of 5 to 1 is specified 
as 500; a ratio of 1 to 2 is specified as 50). The range is 1 to 
infinity. The default value is 2 CPU-toun'3 tasks to 1 I/O-bound 
task. 

• The low limit for the time interval. The default is 20 
milliseconds. 

• The initial delta by which the time interval will be modified. The 
default value is 5 milliseconds. 

• The length of the statistics intervail. The default is 10 seconds. 

Any tasks that are created by an ATTACH issued hy a task in a dynamic 
dispatching partition are also part of the dynamic dispatch group. The 
LPMOD and DPMOD parameters are ignored for these subtasks. A task can- 
not issue a CHAP inacro instruction to move itself into or out of a 
dynamic dispatGhing partition; the CHAP instruction results in a NOP. 

Time slicing and dynamic dispa;tching may not exist within the same 
partition, but they may coexist within the system. 



Dynamic Dispatchihg (VS2) 

Dynamic !Dis patching (also called Heuristic Dispatching) in VS2 is an 
optional feature of the operating system. The user can select a sche- 
duling priority which is to be dynamically dispatched by specifying the 
APG (Authorized Prograir Group) parameters of the CNTRLPROG macro 
inistruction at System Generation. 

The dynamic aisjatching algorithm calc dispatching priorities 

so tasks can use syst^ni resources mo^re efficiently. The algorithm not 
only alters the handling of each task as the task's Gharacteristics 
change, but the algorithm also evalusttes itself and alters itself , based 
on its effectiveness in handling the tasks under its control. 

The algorithm distinguishes between I/O-bound tasks and CPU-bound 
tasks; l/O^bouhd tasks receive the higher priority. Initially, all 
tasks are desabepfiated 1/O-^bound; any »iew tasks entering the dynaitiically 
dispatch^ groi2t|) are aliso desi^gnated l/O-bwnd^ As each task is dis- 
patched, its a<^t^l?v^ifty ;is fflona^^ 

At the end of this ^intei?val «ach tasic is d^^ignated I/O- bound or 
CPU- bound. 
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Dynamic Dispatching assumes that a task is likely to be I/O-bound the 
next time it is dispatched if it was I/O-bound the last time it was 
dispatched. 



Each time a task in the dynamically dispatched group relinquishes 
control of the CPU, its relative position within the task queue may 
change as shown in Figure 6B. 

I/O-bound tasks that remain I/O-bound tend to migrate higher in the 
queue as other I/O-bound tasks change status and join the CPU-bound task 
queue. A task that changes from I/O-bcund to CPU- bound receives the 
highest dispatching priority within the CPU-bound group. In contrast, a 
CPU-bound task that switches to the I/O-bound group has the lowest 
priority within the I/O-bound group. This mechanism aids in making a 
finer distinction between tasks with relatively constant I/O activity 
and those tasks characterized by many status changes. 

The cyclic movement of the CPU- bound tasks ensures that they will all 
share in any available CPU time. Therefore, these tasks have increased 
chances to change their status; potential I/C tasks are not locked in at 
the bottom of the CPU-bound queue. 
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Preemption by I/O task or 
by task above the APG 

Time interval end 



CPU 



CPU 



Voluntary surrender 



I/O 



Save unused portion of interval; 
pass control to preempting task. 

Set up full interval for next 
dispatch of task; queue task at 
end of CPU subgroup; locate next 
task by searching from top of 
CPU subgroup. 

Set up full interval for next 
dispatch of task; queue task at 
end of I/O subgroup and mark 
task I/O-oriented; locate next 
task by searching from top of 
CPU subgroup. 



Figure 6B. Factors in the dispatching of APG tasks 
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TIME SLICING 

Time slicing is a fea-^ure of the op^^^^ system which enables tasks 

that are!^ members of a time- slicing gr^ share control of the CPU. 

When a memiaer of the time-sliqing; group has been active for a certain 
lengthyGf time,, it is interrupted, and control is given to another meirb- 
er: of the , group. In tJcixs yihy, ^ are given equal slices 

of CPU time; no task can use the CPO to thie exclusion of all others 

Any task or silfetask is a ireniber 6f a tiire-S,licing group if its dis- 
patchim^ priorit:y . is within the range cf ^^t priorities 
cu^^ig;p^a i to ]g)artiti6n3 designatedi fd^ time slicing. Pi task or subtask 
can us^ the CHAP ^^m^ a meniber of the time- 

slicing group if, its limit pfioirity is egiial to or greater than the low- 
est disjjatchin^f, priority of the time-slicing group. Also, an originat- 
ing task can vise the ATTACH or CHAP macro instruction to designate a 
subtask_ as a niembef of the tirne-slicing group if the limit priority of 
the .originating task is equal to Qi: grciater than the lowest dispatching 
priority of the time-slicing group. 

VSl Systems 

Each partition has a range of eleven dispatching priorities assigned 
to it. The range of dispatching priorities for a time-slicing group is 
from the highest dispatching priority of the highest priority partition 
within the group to the lowest dispatching priority for the lowest pri- 
ority partition within the group (see Figure 7). For example, if par- 
titions 6 through 8 were assigned to the time-slicing group, any task or 
subtask whose dispatching priority fell within the range 185-153 would 
be a member of the time-slicing group. If the system log and 



I Partition Number | Highest Dispatching j Lowest Dispatching | 

|. — __^^__.„_.^..__«_— ^ 

I 0 I 

I 1 I 

I 2 I 

I 3 I 218 I 208 I 

I ^ I 

I 5 I 

I 6 I 

I 7 I 

I 8 I 

I 9 I 

I 10 I 

I 11 I 

I 12 I 119 I 109 I 

I 13 I 

I 1** I 

I 15 I 

I 16 I 75 I 65 I 

I 17 I 

I 18 I 

I 19 I 

I 20 I 

I 21 I 

I 22 I 9 I 1 I 

I . 23-n 1 

i Reduce the di^^ for each of the f ol- j 
jlpwirig f unctions included in the systein: system log, system | 

j management facility, I/O recoveiry management support. | 

Figure 7 . Dispatching piridfities of partitions 
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system management facility functions were included in the systeir, the 
range of time-slicing dispatching priorities would be 183-151. 

VS2 Systems 

At system generation, your installation designates certain job 
priorities for time slicing. Your tasks are members of the time-slicing 
group if their dispatching priorities correspond to these job priori- 
ties. For example, if job priorities 8 and 9 are designated, tasks are 
members of the time-slicing group when their dispatching priorities can 
be computed as follows: 

For job priority 8, 

Dispatching Priority = (8 x 16) ♦ 11 = 139 

For job priority 9, 

Dispatching Priority = (9 x 16) ♦ 11 = 155 

In this example, tasks with priorities 139 and 155 are members of the 
time-slicing group. Note that time slicing applies only to ready tasks 
with the highest priority; a task with priority 155 would not be inter- 
rupted to give control to a task with priority 139. 

Time slicing is important chiefly in real-time applications, but it 
affects the use of the ATTACH and CHAP macro instructions by all tasks 
in the system. These macro instructions determine task priorities, and 
therefore determine meirbership in the time-slicing group. In using 
these macro instructions, you must consider carefully the priorities for 
which time slicing is performed at your installation. Using the ATTACH 
and the CHAP macro instructions can affect dispatching priorities, as 
discussed above. 

consider again the example in which time slicing is perform.ed for job 
priorities 8 and 9. If a job-step task has an initial dispatching 
priority of 139, it is initially a member of the time-slicing group. If 
it lowers its priority, it is no longer a iremter of the group; if it 
attaches a subtask, the subtask is a member only if it is assigned a 
dispatching priority of 139 (the limit priority of the job-step task). 

If another job-step task is assigned an initial dispatching priority 
greater than 155, it is not initially a member of the tiire-slicing 
group. However, it can create lower priority subtasks that are members 
of the time-slicing group, and can itself become a member by lowering 
its own dispatching priority to 155 or 139. Note that careless use of 
the ATTACH and CHAP macro instructions could result in a task's becoming 
a member of the time-slicing group when time slicing is not actually 
intended. 



TASK AND SUBTASK COMMUNICATIONS 

The task management information in this section is required only for 
establishing communications among tasks in the same job step. The rela- 
tionship of tasks in a job step is shown in Figure 8. The horizontal 
lines in Figure 8 separate originating tasks and subtasks; they have no 
bearing on task priority. Tasks A, Al, A2, A2a, B, Bl, and Bla are all 
subtasks of the job-step task; tasks Al, A2, and A2a are subtasks of 
task A. Tasks A2a and Bla are the lowest level tasks in the job step. 
Although task Bl is at the same level as tasks Al and A2, it is not con- 
sidered a subtask of task A. 

Task A is the originating task for both tasks Al and A2, and task A2 
is the originating task for task A2a- A hierarchy of tasks exists 
within the job step. Therefore the jot step task, task A, and task A2 
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are predecessor^ of task A2a, while task B has no direct relationship to 
task A2a- 



All tasks in the joh step compete independently for CPU time; if no 
constraints are provided, the tasks are performed and are terminated 
asynchronously. However, since each task is performing a portion of the 
game job step, some coremunication and constraints tetween tasks are 
required, such as notification of the completion of subtasks. If ter- 
minsition of a predecessor task is atteirpted fcefore all of the subtasks 
are complete, those sufctasks and the predecessor task are abnormally 
terminated. 



Two operands, the ECB and ETXR operands, are provided in the ATTACH 
macro instruction to assist in communication between a subtask and the 
originating task. These operands are used to indicate the normal or 
abnormal termination of a subtask to the originating task. If the iECB 
or ETXB operand, or both, are coded in the ATTACH iracro instruction, the 
task control block of the subtask is not removed from the system when 
the subtask is terminated. The originating task must remove the task 
control block from the system after termination of the subtask. This is 
accomplished by issuing a DETACH macro instruction. The task control 




Figure 8- Iievels of t^isks in a jot step 
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blocks for all subtasks roust be removed before the originating task can 
terminate normally. 

The ETXR operand specifies the address of an end-of-task exit routine 
in the originating task, which is to be given control when the subtask 
being created is terminated. The end-cf-task routine is given control 
asynchronously after the subtask has terminated and must therefore be in 
virtual storage when it is required. After the control program ter- 
minates the sufctask, the end-of-task routine specified is scheduled to 
be executed. It competes for CPU time using the priority of the ori- 
ginating task and can be given control even though the originating task 
is in the wait condition. When the end-of-task routine returns control 
to the control program, the originating task remains in the wait condi- 
tion if the event control block has not been posted. Although the 
DETACH macro instruction does not have to be issued in the end-of-task 
routine, this is a good place for it. 

The ECB operand specifies the address of an event control block (dis- 
cussed under "Task Synchronization") , which is posted by the control 
program when the subtask is terminated. After posting occurs, the event 
control block contains the completion code specified for the subtask. 

If neither the ECB nor the ETXR operand is specified in the ATTACH 
macro instruction, the task control block for the subtask is removed 
from the system when the subtask is terminated. It's originating task 
does not have to issue a DETACH macro instruction. A reference to the 
task control block in a CHAP or a DETACH macro instruction in this case 
is risky as is task termination. Since the originating task is not 
notified of subtask termination, you might refer to a task control block 
that has been removed from the; system, which would cause the active task 
to be abnormally terminated. 
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CHAPTER PROGRAM MANAGEMENT 



This chapter discusses facilities that aid you in designing your pro- 
grains. Included are descriptions of load module structures, facilities 
for passing control between prograirs and the use of associated macro 
instructions. 



LOAD MODULE STRUCTURE TYPES 

Each load module used during a job step can be designed in one of 
three load module structures: simple , planned overlay , or dynamic . A 
simple structure does not pass control to any other load modules during 
its execution, and is brought into virtual storage all at one time. A 
planned overlay structure may, if necessary, pass control to other load 
modules during its execution, and it is not brought into virtual storage 
all at one time. Instead, segments of the load module reuse the same 
area of virtual storage. A dynaunic structure is brought into virtual 
storage all at one time, and passes control to other load modules during 
its execution. Each of the load modules to which control is passed can 
be one of the three structure types. Characteristics of the load module 
structure types are summarized in Figure 9. 

since the large capacity of virtual storage all but eliminates the 
need for complex overlay structures, planned overlays will not be dis- 
cussed further. 

Simple Structure 

A simple structure consists of a single load module produced by the 
linkage editor. The single load module contains all of the instructions 
required and is paged into real storage by the control program as it is 
executed- The simple structure can be the most efficient of the two 
structure types because the instructions it uses to pass control do not 
require control- program assistance. However, any prograit should be 
carefully designed to make most efficient use of paging. 

Dynamic Structure 

A dynamic structure requires more than one load module during execu- 
tion. Each load module required can operate as either a simple struc- 
ture or another dynamic structure. The advantages of a dynamic struc- 
ture over a simple structure increase as the program becomes more com- 
plex, particularly when the logical path of the program depends on the 
data being processed. The load modules required in a dynamic structure 
are paged into real storage when required, and can be deleted from vir- 
tual storage when their use is completed. 
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Figure 9* Characteristics of load modules 
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LOAD MODULE EXECUTION 



Depending on the CQnfiguratiQn of the operating systein and the macro 
instructions used to pass; control, execution of the load modules is 
serial or in parallel. Execution is serial in the VS operatinq system 
unless an ATTACH macro instruction is used to create a new task- The 
new task competes for CPU time independently with all other tasks in the 
system. The load module named in the ATTACH macro instruction is 
executed in parallel with the load module containing the ATTACH macro 
instruction. The execution of the load modules is serial within each 
task. 

The following paragraphs discuss passing control for serial execution 
of a load module. Creation and management of new tasks is discussed 
under the headings "Task Creation and Control." 



PASSIMG CONTROL IN A SIMPLE STRUCTURE 

There are certain procedures to follow when passing control to an 
entry point in the same load module. The established conventions to use 
when passing control are also discussed. These procedures and conven- 
tions are the framework for all program interfaces. Knowledge of the 
information about addressing contained in the VS Assemfcler Language pub- 
lication is required. 



PASSING CONTROL WITHOUT RETURN 

Some control sections pass control to another control section of the 
load module and do not receive control back. An example of this type of 
control section is a housekeeping routine at the beginning of a program 
which establishes values, initializes switches, and acquires buffers for 
the other control sections in the program. The following procedures 
should be used when passing control without return. 

Preparing to Pass Control 

Because control will not be returned to this control section, you 
must restore the contents of register lU. Register lU originally con- 
tained the address of the location in the calling program (for example, 
the control program) to which control is to be passed when your program 
is finished. Since the current control section does not make the return 
to the calling program, the return address must be passed to the control 
section that makes the return. In addition, the contents of registers 
2-12 must be unchanged when your program eventually returns control, so 
these registers must also be restored. 

If control were being passed to the next entry point from the control 
program, register 15 would contain the entry address ^ You should use 
register 15 in the same way, so that the called routine remains indepen- 
dent of the program that passed control to it. 

Register 1 should be used to pass parameters. A parameter list 
should be established, and the address of the list placed in register 1. 
The parameter list should consist of consecutive fullwords starting on a 
full word boundary, each fullword containing an address to be passed to 
the called control section in the three low-order bytes of the word. 
The high-order bit of the last word should be set to 1 to indicate that 
it is the last word of the list. The system convention is that the list 
contain addresses only. You may, of course, deviate from this conven- 
tion ; however , when you deviate from any systeir convention, you restrict 
the use of your programs to those programmers who are aware of your spe- 
cial conventions. 
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since you have reloaded all the necessary registers, the save area 
that you used is now available, and can be reused by the called control 
section- You pass the address of the save area in register 13 just as 
it was passed to you. By passing the address of the old save area, you 
save the 72 bytes of virtual storage for a second, and unnecessary, save 
area - 

Passing Control 

The common way to pass control between one control section and an 
entry point in the same load module is to load register 15 with a V-type 
address constant for the name of the external entry point, and then to 
branch to the address in register 15. The external entry point must 
have been identified using an ENTRY instruction in the called control 
section if the entry point is not the same as the control section's 
name. 

An example of loading registers and passing control is shown in 
Figure 10. In this example, no new save area is used, so register 13 
still contains the address of the old save area. It is also assumed for 
this example that the control section will pass the same parameters it 
received to the next entry point. First, register 14 is reloaded with 
the return address. Next, register 15 is loaded with the address of the 
external entry point NEXT, using the V-type address constant at the 
location NEXTAODR. Registers 0-12 are reloaded, and control is passed 
by a branch instruction using register 15. The control section to %ihich 
control is passed contains an ENTRY instruction identifying the entry 
point NEXT. 

An example of passing a parameter list is shown in Figure 11. Early 
in the routine the contents of register 1 (that is, the address of the 





L 


14,12(13) 


CSECT 




L 


15, NEXTADDR 


ENTRY NEXT 




LM 


0,12,20(13) 






BR 


15 


->NEXT SAVE (14,12) 


NEXTADDR 


DC 


V(NEXT) 


• • ■ 




Figure 


10. Passing control in a simple structure 
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Figure 11. Passing control with a parameter list 
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fullword containing the PARM field address) were, stored at the fullword 
PiVRMADDR, Register X 3 is loaded with the address of the old save area, 
wbici^ haid been saved in woird 2 of the new save area. The contents of 
yegist^r 1ft are restored, and register 15 is loaded with the entry 
address. 

The address of the list of parameters is loaded into register 1. 
These parameters include the addresses of two data control blocks (DCBs) 
and the original register 1 contents. The high-order bit in the last 
address parameter (PARMADDR) is set to 1 using an OR-iramediate instruc- 
tion; The contents of registers 2-12 are restored- (since one of these 
registers was the base register, restoring the registers earlier would 
have made the parameter list unaddress able . ) A branch instruction using 
iregister 15 passes control to entry point NEXT. 



PASSING CONTROl. WITH RETURN 

The control program passed control to your program, and your program 
will return control when it is through processing. Similarly, control 
sections within your program will pass control to other control sec- 
tions, and expect to receive control back. An example of this type of 
control section is a monitoring routine; the monitor determines the ord- 
er of execution of other control sections based on the type of input 
<^ata. The following procedures should be used when passing control with 
return. 



Preparing to Pass Control 

Registers 15 and 1 are used in the same manner they are used to pass 
control without return. Register 15 contains the entry address in the 
new control section and register 1 is used to pass a parameter list. 

Register 14 must contain the address of the location to which control 
is to be returned when the called control section completes execution. 
The address can be the instruction following the instruction which 
causes control to pass, or it can be another location within the current 
control section designed to handle all returns. Registers 2-12 are not 
involved in the passing of control; the called control section should 
not depend on the contents of these registers in any way. 

You should provide a new save area for use by the called control sec- 
tion as previously described, and the address of that save area should 
be passed in register 13. Note that the same save area can be reused 
after control is returned by the called control section. One new save 
area is ordinarily all you will require regardless of the number of con- 
trol sections called. 



Passing Control 

Two standard methods are used for passing control to another control 
section and providing for return of control. One is an extension of the 
method used to pass control without a return, and requires a V-type 
address coi)stant and a branch or a branch and link instruction. The 
other method uses the CALL macro instruction to provide a parameter list 
and establish the entry and return addresses. Using either method, the 
entry point must be identified by an ENTRY instruction in the called 
control section if the entry name is not the same as the control section 
name. Figures 12 and 13 illustrate the two methods of passing control; 
in each example, it is assumed that register 13 already contains the 
address of a new save area. 
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Figure 12. Passing control with return 



I RETURNPT 
I AREA 



CALL NEXT , ( INDCB , OUTDCB , AREA) , VL 
DC 12F'0' 

Figure 13. Passing control with CALL 



Use of an inline parameter list and an answer area is also illus- 
trated in Figure 12. The address of the external entry point is loaded 
into register 15 in the usual manner. A branch and link instruction is 
then used to branch around the parameter list and to load register 1 
with the address of the parameter list. An inline parameter list such 
as the one showi in Figure 12 is convenient when you are debugging 
because the parameters involved are located in the listing (or the dump) 
at the point they are used, instead of at the end of the listing or 
dump. Note that the first byte of the last address parameter (ANSWERAD) 
is coded with the high-order bit set to 1 to indicate the end of the 
list. The area pointed to by the address in the ANSWERAD parameter is 
an area to be used by the called control section to pass parameters back 
to the calling control section. This is a possible method to use when a 
called control section must pass parameters back to the calling control 
section. Parameters are passed back in this manner so that no addition- 
al registers are involved. The area used in this example is twelve 
words; the size of the area for any specific application depends on the 
requirements of the two control sections involved. 

The CALL macro instruction in Figure 13 provides the same functions 
as the instructions in Figure 12. When the CALL macro instruction is 
expanded, the operands cause the following results; 

NEXT 

A V-type address constant is created for NEXT, and the address is 
loaded into register 15. 

(INDCB, OUTDCB, AREA) 

A-type address constants are created for the three parameters coded 
within parentheses, and the address of the first A-type address 
constant is placed in register 1. 

VL 

The high-order bit of the last A-type address constant is set to 1. 

control is passed to NEXT using a branch and link instruction. The 
address of the instruction following the CALL macro instruction is 
loaded intp register 14 before control is passed. 
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In addition to the results described above, the V-type address con- 
stant generated by the CALL macro instruction causes the load module 
witlj the; entry point NEXT to be automatically edited into the same load 
pp^^iXe ai3 the control section containing the CALL macro instruction. 
Ref0r to the Linkage Editor and Loader publication, if you are 
intejrested in finding out more about this service. 



The pajrametei: list constructed from the call macro instruction in 
Figiiire 13, contains only A-type address constants. A variation on this 
type ©f parameter iist results from the following coding: 



CALL NEXT, (INDCB, (6) , (7)) ,VL 

In the above CALL macro instruction, two of the parameters to be passed 
are coded as registers rather than symbolic addresses. The expansion of 
this macro instruction again results in a three-word parameter list; in 
this example, however, the expansion also contains instructions that 
store the cpntents of registers 6 and 7 in the second and third words, 
respectively, of the parameter list. The high-order bit in the third 
word is set to 1 after register 7 is stored. You can specify as many 
address parameters as you need, and you can use symbolic addresses or 
register contents as you see fit. 



Anj^lyzinq the Return 

When control is returned from the control program after processing a 
system macro instruction, the contents of registers 2-13 are unchanged. 
When control is returned to your control section from the called control 
section, registers 2-14 contain the same information they contained when 
control was passed^ as long as system conventions are followed. The 
called control section has no obligation to restore registers 0 and 1; 
so the contents of these registers may or may not have been changed. 

When control is returned, register 15 can contain a return code indi- 
cating the results of the processing done by the called control section. 
If used, the return code should be a multiple of U, so a branching table 
can be used easily, and a return code of 0 should be used to indicate a 
normal return. The control program frequently uses this method to ind- 
icate the results of the requests you make using system macro instruc- 
tions; an example of the type of return codes the control program pro- 
vides is shown in the description of the IDENTIFX macro instruction. 

The meaning of each of the codes to be returned must be agreed upon 
in advance. In some cases, either a "good" or "bad" indication (zero or 
nonzero) will be sufficient for you to decide your next action. If this 
is true, the coding in Figure 14 could be used to analyze the results. 
Many times, however, the results a^nd the alternatives are more compli- 
cated, and a branching table, such as shown in Figure 15, could be used 
to pass control to the proper routine. 



Note ; Explicit tests are required to ensure that the return code value 
does not exceed the branch table size. Never assume that no expansion 
of return codes will occur. 



f RETURNPT LTR 15,15 Test return code for zero 1 

j BNZ ERRGKTN Branch if not zero to error routine | 

1^- ... . I 

L- . — _ : ■ — — : — : .-.-J 

Figure 14. Test for normal return 
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Figure 15. Return code test using branching table 



How Contr ol is Retur ned 

In the discussion of the return under "Analyzing the Return" it was 
indicated that the control section returning control must restore the 
contents of registers 2-1 U. Because these are the same registers 
reloaded when control is passed without a return, refer to the discus- 
sion under "Passing Control Without Return" for detailed information and 
examples. The contents of registers 0 and 1 do not have to be restored. 



Register 15 can contain a return code when control is returned. As 

indicated previously, a return code should be a multiple of four with a 
return code of zero indicating a normal return. The return codes other 
than zero thai you use can have any meaning, as long as the control sec- 
tion receiving the return codes is aware of that meaning. 



The return oddress is the address originally passed in register 14; 
control should always be returned to that address. You can either use a 
branch instruction such as BR lU, or you can use the RETURN macro 
instruction. An example of each methiod of returning control is dis- 
cussed in the following paragraphs. 

Figure 16 is a ^xjrtion of a control section used to analyze input 
data cards and to check for an out~of-tolerance condition- Each time an 
out-of-tolerance condition is found, in addition to some corrective 
action, one is added to the value at the address STATUSBY. After the 
last data card is analyzed, this control section returns to the calling 
control section, which bases its next action on the number of out-of- 
tolerance conditions encountered- The coding shown in Figure 16 loads 
register 13 with the address of the save area this control section used 
and register ll with the return address. The contents of register 15 
are set to zero, and the value at the address STATDSBY (the number of 
errors) is placed in the low-order eight bits of the register. The con- 
tents of register 15 are shifted to the left two places to make the 
value a multiple of four. Registers 2-12 are reloaded, and control is 
returned to the address in register lU. 

The R£;turn macro instruction is provided to save coding time. The 
expansion of the RETURN macro instruction provides instructions that 
restore a designated range of registers, load return code in register 
15, and branch to the address in register 14. In addition, the RETURN 
macro instruction can be used to flag the save area used by the return- 
ing control section; this flag, a byte containing all ones, is placed in 
the high-order byte of word four of the save area after the registers 
have been restored- The flag indicates that the contrql section that 
used the s^ve area has returned to the calling control/section- You 
will find that the flag is useful when tracing the flow of your program 
in a dump. For a complete record of program flow, a separate save area 
must be provided by each control section each time control is passed. 
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STATUSBy 



L 


13,4(13) 


L 


14,12C13) 


SR 


15,15 


IC 


15, STATUSBY 


SLA 


15,2 


LM 


2,12,28(13) 


BR 


lU 


DC 


X'OO' 



Load address of previous save area 

Load return address 

Set register 15 to zero 

Load number of errors 

Set return code to multiple of 4 

Reload registers 2-12 

Return 



Figure 16. Establishing a return code 



STATUSBY 



L 13,4(13) 

L lU, 12(13) 

SR 15,15 

IC 15, STATUSBY 

SLA 15,2 

RETURN (2,12) ,RC=(15) 



Restore save area address 

Return address in register 14 

Zero register 15 

Load number of errors 

Set return code to multiple of 4 

Reload registers and return 



DC X»00' 

Figure 17. Using the RETURN macro instruction 



L 13,4(13) 
RETURN (14,12),T,RC=8 



Figure 18. RETURN macro instiruction with flag 



TJie cQntents of register 13 must be restored before the RETURN macro 
instruction is issued. The registers to be reloaded should be coded in 
the same order as they would have been designated had a load-multiple 
(LM) instruction been coded. You can load register 15 with the return 
code before you write the RETURN macro instruction, you can specify the 
return code in the RETURN macro instruction, or you can reload register 
15 from the save area. 

The coding shown in Figure 17 provides the same result as the coding 
shown in Figure 16. Registers 13 and 14 are reloaded, and the return 

code is loaded in register 15. The RETURN macro instruction reloads 
registers 2-12 and passes control to the address in register 14. The 
save area used is not flagged. The RC-(15) operand indicates that 
register 15 already contains the return code, and the contents of 
register 15 are not to be altered. 

Figure 18 illustrates another use of the RETURN macro instruction. 
The correct save area address is again established, and then the RETURN 
macro instruction is issued. In this example, registers 14 and 0-12 are 
reloaded, a return code of 8 is placed in register 15, the save area is 
flagged, and control is returned- Specifying a return code overrides 
the request to restore register 15 even though register 15 is within the 
designated range of registers. 
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Return to the Control Program 



The discussion in the preceding paragraphs has covered passing con- 
trol within one load module, and has been based on the assumption that 
the load module was brought into virtual storage because of the program 
name specified in the EXEC statement. The control program established 
only one task to be performed for the job step- When the logical end of 
the program is reached, control passes to the return address passed (in 
register 14) to the first control section in the progrcun. When the con- 
trol program receives control at this point, it terminates the task it 
created for the job step, compares the return code in register 15 with 
any COND values specified on the JOB and EXEC statements, and determines 
whether or not subsequent job steps, if any are present, should be 
executed. 



PASSING CONTROL IN A DYNAMIC STRUCTURE 

The discussion of passing control in a simple structure provides the 
background for the discussion of passing control in a dynamic structure. 
Within each load module, control should be passed as in a simple struc- 
ture. If you can determine which control sections will make up a load 
module before you code the control sections, you should pass control 
within the load module without involving the control program. The macro 
instructions discussed in this section provide increased linkage capabi- 
lity, but they require control prograun assistance and possibly increased 
execution time. 



BRINGING THE LOAD MODULE INTO VIRTUAL STORAGE 

The load module containing the entry name you specified on the EXEC 
statement is automatically brought into virtual storage by the control 
program. Any other load modules you require during your job step are 
brought into virtual storage by the control program when requested; 
these requests are made by using the LOAD, LINK, ATTACH, and XCTL macro 
instructions. The following paragraphs discuss the proper use of these 
macro instructions. 

Location of the Load Module 

Initially, each load module that you can obtain dynamically is 
located in a library (partitioned data set). This library is the link 
library, the job or step library, task library, or a private library. 

• The link library is always present and is available to all job steps 
of all jobs. The control program provides the data control block 
for the library and logically connects the library to your program, 
making the members of the library available to your program. 

• The job and step libraries are explicitly established by including 
//JOBLIB and //STEPLIB DD statements in the input stream. The 
//JOBLIB DD Statement is placed immediately after the JOB statement, 
while the //STEPLIB DD statement is placed among the DD statements 
for a particular job step. The job library is available to all 
steps of your job, except those that have step libraries. A step 
library is available to a single job step; if there is a job 
library, the step library replaces the job library for the step- 
For either the job library or the step library, the control program 
provides the data control block and issues the OPEN ionacro instruc- 
tion to logically connect the library to your program. 

• In VS2 systems, unique task libraries may be established by using 
the TASKLIB operand of the ATTACH macro instruction. The issuer of 
the ATTACH macro instruction is riesponsible for providing the DD 
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statement and opening the data set or sets. If the TASKilB operand 
is ondtted, the task library of the attaching task is propagated to 
the attached task. In the following example, task A's job library 
is LIBl. Task A attaches task B, specifying TASKLIB=LIB2 in the 
ATTACH macro instruction. Task B's task library is therefore LIB2. 
When task B attaches task C, LIB2 is searched for task c before LIBl 
or the link library. Because task B did not specify a unique task 
library for task c, its own task library (LIB2) is propagated to 
task C and is the first library searched when task C requests that a 
module be brought into virtual storage. 

Task A ATTACH EP=B,TASKLIB=LIB2 

Task B ATTACH EP=C 

• A private library is defined by including a DD statement in the 
input stream and is available only to the job step in vdiich it is 
defined. You must provide the data control block and issue the OPEN 
macro instruction for each data set. You may use more than one 
private library by including more than one DD statement and asso- 
ciated data control block. 

A library can be a single partitioned data set, or a collection of 
such data sets. When it is a collection, you define each data set by a 
separate DD statement, but you assign a name only to the statement that 
defines the first data set. Thus, a job library consisting of three 
partitioned data sets would be defined as follows: 

//JOBLIB DD DSNAME=PDS1 , . . . 
// DD DSNAME=PDS2, . .. 

// DD DSNAME=PDS3,... 

The three data sets (PDSl, PDS2, PDS3) are processed as one, and are 
said to be concatenated . Concatenation and the use of partitioned data 
sets is discussed in more detail in the Data Management Services 
publication. 

Some of the load modules from the link library may already be in vir- 
tual storage in an area called the resident reenterable module area, 
(VSl) , or the link pack area (VS2). The contents of these areas are 
determined during the nucleus initialization process and will vary 
depending on the requirements of your installation. In an operating 
system with VS2, the link pack area contains frequently used, reenter- 
able load modules from the LFA library, along with data management load 
modules; these load modules can be used by any job step in any job. If 
TSO is in the system and is started, it extends the link pack area. The 
resident reenterable module area can contain user-viritten modules and 
the loader, discussed in the Linkage Editor and Loader publication, and 
all reenterable graphics subroutine package (GSP) modules. 

With the exception of those load modules contained in this area, 
copies of all of the reenterable load modules you request are brought 
into your area of virtual storage and are available to any task in your 
job step. The portion of your area containing the copies of the load 
modules is called the job pack area. 



The Search for the Load Module 

In response to your request for a copy of a load module, the control 
program searches the job pack area, the resident access module (RAM) 
list (VSl), the task's load list, the link pack area (VS2) , and the 
resident reenterable module area (VSl) . If a copy of the load module is 
found in one of the pack areas, the control program determines whether 
that copy can be used (see "Using an Existing Copy"). If an existing 
copy can be used, the search stops. If it can not be used, the search 
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continues until the module is located in a library. The load nodule is 
then brought into the job pack area or the load list area. 



The order in which the libraries and pack areas are searched depends 
on whether the system is VSl or VS2 and on the operands used in the 
macro instruction requesting the load module. The operands that define 
the order of the search are EP, EPLOC, DE, and DCB. The Ep, EPLOC, and 
DE operands are used to specify the name of the entry point in the load 
module; you code one of the three every time you use a LINK, LOAD, XCTL, 
or ATTACH macro instruction. The DCB operand is used to indicate the 
address of the data control block for the library containing the load 
module, and is optional. Omitting the DCB operand or using the DCB 
operand with an address of zero specifies the data control block for the 
link library or the job or step library. 

The following paragraphs discuss the order of the search when the 
entry name used is a member name. 

The EP and EPLOC operands require the least effort on your part; you 
provide only the entry name, and the control program searches for a load 
module having that entry name. Figure 19 shows the order of the search 
when EP or EPLOC is coded, and the DCB operand is omitted or DCB=0 is 
coded. 

When used without the DCB operand, the EP and EPLOC operands provide 
the easiest method of requesting a load module from the link, job, or 
step library. In a system with VS2, the task libraries are searched 
before the job or step library, beginning with the task library of the 
task that issued the request and continuing through the task libraries 
of all its antecedent tasks. The job or step library is then searched, 
followed by the link library. In VSl, the data sets that make up these 
libraries are searched in the order of their DD statements. 

A job, step, or link library or a data set in one of these libraries 
can be used to hold one version of a load module, while another can be 
used to hold another version with the same entry name. If one version 
is in the link library, you can ensure that the other will be found 
first by including it in the job or step library. However, if both ver- 
sions are in the job or step library, you roust define the data set that 
contains the version you want to use before that which contains the oth- 
er version. For example, if the wanted version is in PDSl and the 
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I The job pack area (user storage) |The job pack area of the region is 

I is searched. | searched for an available copy 

^ + 

I The step library or the job |The requesting task's task 

j library (if any) is searched. If (library and all the unique task 
I both libraries are specified, the | libraries of its antecedent tasks 
1 job library is not searched. |are searched. 

t > _„ 

I The link pack area or the resident (The step library is searched; if 
I reenterable load module area is [there is no step library, the job 
1 searched (optional). j library (if any) is searched. 

I The link library is searched. ( The link pack area is searched. 

I j. 

I I The link library is searched. 

L , X . 

Figure 19. Search for module, EP or EPLCX: operand with DCB=0 or DCB 
operand omitted 
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unwanted version is in PPS2, a step library consisting of thefse data 
sets should be defined as follows: 



//STIPLIB m DSNAWE=PDS1, , 
// DD DSNAWE=PDS2 , . , , 

If, however, the first version in the job or step library has been pre- 
viously loaded i^nd the version in the link library or the second version 
in the job library is desired, the DCB operand roust be coded in the 
macro instruction . 

This is not the case for task libraries. Extreme coution should be 
used when specifying module names in unique task libraries, because 
duplicate names may lead to the wrong module being given to the task 
requesting that the module be brought into virtual storage- Once a 
module has been loaded, the module name is known to all tasks in the 
region and a copy of that module is given to all tasks requesting that 
that module name be loaded, regardless of the requester's task library. 

If you know that the load module you are requesting is a member of 
one of the private libraries, you can still use the EP or EPLOC operand, 
this time in conjunction with the DCB operand. You specify the address 
of the data control block for the private library in the DCB operand. 
The order of the search for EP or EPLOC with the DCB operand is shown in 
Figure 20. 

Searching a job or step library slows the retrieval of load modules 
from the link library; to speed this retrieval, you should limit the 
size of the job and step libraries. You can best do this by eliminating 
the job library altogether and providing step libraries where required. 
You can limit each step library to the data sets required by a single 
step; some steps (such as compilation) do not require a step library and 
therefore do not require searching and retrieving modules from the link 
library. For maximum efficiency, you should define a job library only 
when a step library would be required for every step, and every step 
library would be the same. 

The DE operand requires more work than the EP and EPLOC operands, but 
it can reduce the amount of time spent searching for a load module. 
Before you can use this operand, you must use the BLDL macro instruction 
to obtain the directory entry for the module. The directory entry is 
part of the library that contains the module. 
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I The resident reenterable load j The specified library is j 

[module area is searched j searched. j 

I (optional). j | 

I The specified library is jThe link pack area is searched. | 

I searched. jr — -H 

i |The link library is searched. j 
L, , , ._ jL . : _j 

Figure 20. 3earGli for module, EP or EPLOC operands with dcb operand 
specifying private library 
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To save time, the BLDL macro instruction used must obtain directory 
entries for more than one entry name. You specify the names of the load 
modules and the address of the data control block for the library when 
using the BLDL macro instruction; the control program places a copy of 
the directory entry for each entry name requested in a designated loca- 
tion in virtual storage. If you specify the link library and the job or 
step library, the directory information indicates from which library the 
directory entry was taken. The directory entry always indicates the 
relative track and block location of the load module in the library. If 
the load module is not located on the library you indicate, a rettim 
code is given. You can then issue another BLDL macro instruction speci- 
fying a different library. 

To use the DE operand, you provide the address of the directory entry 
and code or omit the DCB operand to indicate the same library specified 
in the BLDL macro instruction. The order of the search when the DE 
operand is used is shown in Figure 21 for the link, job, step, and priv- 
ate libraries. 

The preceding discussion of the search is based on the premise that 
the entry name you specified is the member name. In an operating system 
with VSl, the same search results from specifying an alias rather than a 
member name. When you are using VS2, the control program checks for an 
alias entry point name when the load module is found in a library. If 
the name is an alias, the control program obtains the corresponding 
member name from the library directory, and then searches the link pack 
and job pack areas using the member name to determine if a usable copy 
of the load module exists in virtual storage. If a usable copy does not 
exist in a pack area, a new copy is brought into the job pack area. 
Otherwise, the existing copy is used, conserving virtual storage and 
eliminating the loading time. 

As the discussion of the search indicates, you should choose the 
operands for the macro instruction that provide the shortest search 
time. The search of a library actually involves a search of the direc- 
tory, followed by copying the directory entry into virtual storage, fol- 
lowed by loading the load module into virtual storage. If you know the 
location of the load module, you should use the operands that eliminate 
as many of these unnecessary searches as possible, as indicated in 
Figures 19, 20, and 21. Examples of the use of these figures are shown 
in the following discussion of passing control. 



Using an Existing Copy 

The control program uses a copy of the load module already in the job 
pack area if the copy can be used. Whether the copy can be used or not 
depends on the reusability and current status of the load module; that 
is, the load module attributes, as designated using linkage editor con- 
trol statements, and whether the load module has already been used or is 
in use. The status information is available to the control program only 
when you specify the load module entry name on an EXEC statement, or 
when you use ATTACH, LINK, or XCTL macro instructions to transfer con- 
trol to the load module. The control program protects you from obtain- 
ing an unusable copy of a load module if you always "formally* request a 
copy using these macro instructions (or the EXEC statement) ; if you pass 
control in any other manner (for instance, a branch or a CALL macro 
instruction) , the control program, because it is not informed, cannot 
protect you. 

Operating System with VSl ; The LOAD macro instruction permits all tasks 
in a partition to share the same copy of a reenterable module requested 
by a previous LOAD macro instruction. If the reenterable module is lat- 
er reques|:ed by a LINK, XCTL, or ATTACH macro instruction and a previous 
request i# still active, the existing copy of the module is used. 
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VSl 



VS2 



Directory Entry Indicates Link Library and DCB=0 or DCB Operand 
Omitted 



The partition is searched. 



The job pack area for the region 
is searched for an available copy. 



The resident reenterable load 
module area is searched 
(optional) , 



The link pack area is searched. 



The module is obtained from the 
link library. 



The module is obtained from the 
link library. 



Directory Entry Indicates Job, Step, or Task Library and DCB=0 or 
DCB Operand Omitted 



the job pack area for the parti- j The job pack area for the region 
tion is searched for an avail- | is searched for an available copy, 
able copy. | 



The module is obtained from the 
step library; if there is no 
step library, the module is 
obtained from the job library. 



I The module is obtained from the 
I step library; if there is no step 
I library, the module is obtained 
I from the job library. 
^— , - — -X ■ — . 

DCB Operand Indicates Private Library 



The job pack area for the parti- j The job pack area for the region 
tion is searched for an avail- | is searched for an available copy, 
able copy. | 



The module is obtained from the 
specified private library. 



I The module is obtained from the 
I specified private library. 
I . . X — - ; 

Figure 21. Search for module using DE operand 



Operating System with VS2 ; All reenterable modules (modules designated 
as reenterable using the linkage editor) from any library are completely 
reusable; only one copy is ever placed in the link pack area or brought 
into your job pack area, and you get immediate control of the load 
module. If the module is serially reusable, only one copy is ever 
placed in the job pack area; this copy is always used for a lOAD macro 
instruction. If the copy is in use, however, and the request is made 
using a LINK, ATTACH, or XCTL macro instruction, the task requiring the 
load module is placed in a wait condition until the copy is available. 
A LINK macro instrucion should not be issued for a serially reusable 
load module currently in use for the same task; the task will be abnorm- 
ally terminated. (This could occur if an exit routine issued a LINK 
macro instruction for a load module in use by the main program.) 

If the load module is not reusable, a LOAD macro instruction will 
always bring in a new copy of the load module; an existing copy is used 
only if a LINK, ATTACH, or XCTL macro instruction is issued and the copy 
has not been used previously. Remember, the control program can deter- 
mine if a load module has been used or is in use only if all of your 
requests are made using LINK, ATTACH, or XCTL macro instructions. 

Using the LOAD Macro Instruction 

The LOAD macro instruction is used to ensure that a copy of the spe- 
cified load module is in virtual storage in your partition/region or job 
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pack area if it was not preloaded into the resident reenterable module 
area, the resident access method area, or the link pack area. When a 
LOAD macro instruction is issued, the control program searches for the 
load module as discussed previously and brings a copy of the load module 
into the partition/region if required. When the control program returns 
control, register 0 contains the virtual storage address of the entry 
point specified for the requested load module, and register 1 contains 
the length of the loaded module and the authorization code in the high 
byte- Normally, the LOAD macro instruction is used only for a reenter- 
able or serially reusable load module, since the load module is retained 
even though it is not in use. 

The control program also establishes a "responsibility" count for the 
copy, and adds one to the count each time the requirements of a LOAD 
macro instruction are satisfied by the same copy. As long as the 
responsibility count is not zero, the copy is retained in virtual 
storage. 

The responsibility count for the copy is lowered by one when a DELETE 
macro instruction is issued during the task which was active when the 
LOAD macro instruction was issued. When a task is terminated, the count 
is lowered by the number of LOAD macro instructions issued for the copy 
when the task was active minus the number of deletions. When the 
responsibility count for a copy in a job pack area reaches zero, the 
virtual storage area containing the copy is made available; the copy is 
never reused after the responsibility count established by LOAD macro 
instructions reaches zero. 



PASSING CONTROL WITH RETURN 

The LINK macro instruction is used to pass control between load 
modules and to provide for return of control. You can also pass control 
using branch or branch and link instructions or the CALL macro instruc- 
tion; however, when you pass control in this manner you must protect 
against multiple uses of nonreusable or serially reusable modules. The 
following paragraphs discuss the requirements for passing control with 
return in each case. 

The LINK Macro Instruction 

When you use the LINK macro instruction , as far as the logic of your 
program is concerned, you are passing control to another load module. 
Remember, however, that you are requesting the control program to assist 
you in passing control. You are actually passing control to the control 
program, using an SVC instruction, and requesting the control program to 
find a copy of the load module and pass control to the entry point you 
designate- There is some similarity between passing control using a 
LINK macro instruction and passing control using a CALL macro instruc- 
tion in a simple structure. These similarities are discussed first. 

The convention regarding registers 2-12 still applies; the control 
program does not change the contents of these registers, and the called 
load module should restore them before control is returned. You must 
provide the address in register 13 of a save area for use by the called 
load module; the control program does not use this save area. You can 
pass address parameters in a parameter list to the load module using 
register 1; the LINK macro instruction provides the same facility for 
constructing this list as the CALL macro instruction. Register 0 is 
used by the control program and the contents will be modified. 

There is also some difference between passing control using a LINK 
macro instruction and passing control using a CALL macro instruction. 
When you pass control in a simple structure, register 15 contains the 
entry address and register 14 contains the return address. When the 
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called load module gets control, that is still what regi3tei:s}l4 and 15 
contain, but when you use the LINK maero instruction, it is trie control 
program that establishes these addresses. When you code the LINK macro 
instruction, you provide the entry name and possibly some library infor- 
mation using the EP, EPLOC, or DE, and DCB operands. But you have to 
get this entry name and library information to the control program. The 
expansion of the LINK macro instruction does this by creating a control 
program parameter list (the information required by the control program) 
and placing the address of this parameter list in register 15- After 
the control program finds the entry name, it places the address in 
register 15. 

The return address in your control section is alwaiys the instruction 
following the UNK; that is not, however, the address that the called 
load module receives in register lU. The control program saves the 
address of the location in your program in its own save area, and places 
in register 14 the address of a routine within the control program that 
will receive control. Because control was passed using the control pro- 
gram, return must also be made using the control program. 

The control program establishes a responsibility count for a load 
module when control is passed using the LINK macro instruction. This is 
a separate responsibility count from the count established for LOAD 
macro instructions, but it is used in the same manner. The count is 
increased by one when a LINK macro instruction is issued and decreased 
by one when return is made to the control program or when the called 
load module issues an XCTL macro instruction. 

Figures 22 and 23 show the coding of a LINK macro instruction used to 
pass control to an entry point in a load module. In Figure 22, the load 
module is from the link, job, or step library; in Figure 23, the module 
is from a private library. Except for the method used to pass control, 
this example is similar to Figures 12 and 13, A problem program para- 
meter list containing the addresses INDCB, OUTDCB, and AREA is passed to 
the called load module; the return point is the instruction following 
the LINK macro instruction. A V-type address constant is not generated, 
because the load module containing the entry point NEXT is not to be 
edited into the calling load module. Note that the EP operand is cho- 
sen, since the search begins with the job pack area and the appropriate 
library as shown in Figure 19. 

Figiires 24 and 25 show the use of the BLDL and LINK macro instruc- 
tions to pass control. Assuming that control is to be passed to an 
entry point in a load module from the link library, a BLDL macro 
instruction is issued to bring the directory entry for the member into 
virtual storage. (Remember, however, that time is saved only if more 
than one directory entry is requested in a BLDL macro instruction. Only 
one is requested here for simplicity.) 



r- • • • " — ■ — — 1 

I LINK EP=NEXT, PARAM= (INDCB, OUTDCB, AREA) ,VL=1 j 

j RETURNPT ... I 

I AREA DC 12F»0' | 

Figure 22. Use of the LINK macro instruction with the job or link 
library 

f OPEN CPVTLIB) 1 

I ... I 

I LINK EP=NEXT,DCB=PVTLIB, PARAM=( INDCB, OUTDCB, AREA) ,VL=1 | 

I ... I 

j PVTLIB DCB DDNAJME=PVTLIBDD,DSORG=PO,MACRF=(R) | 
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Figure 23- Use of the LINK macro instruction with a private library 
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BLDL O.LISTADDR 



LISTADDR 
NAWEADDR 



DS 
DC 
DC 
DC 
DS 



OH 
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CLB'NEXT' 
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List description field: 

Number of list entries 

Length of each entry 
Member name 

Area required for directory information 



Figure 24. Use of the BLDL macro instruction 



I LINK DE=NAMEADDR,DCB=0,PARAM=(INDCB,OUTDCB,AREA) ,VL=1 

L 

Figure 25. The LINK macro instruction with a D£ operand 



The first operand of the BLDL macro instruction is a zero, which 
indicates that the directory entry is on the link or job library. The 
second operand is the address in virtual storage of the list description 
field for the directory entry. The first two bytes at LISTADDR indicate 
the number of directory entries in the list; the second two bytes indic- 
ate the length of each entry. If the entry is to be used in a LINK, 
LOAD, ATTACH, or XCTL macro instruction, the entry must be 58 bytes in 
length. A character constant is established to contain the directory 
information to be placed there by the control program as a result of the 
BLDL macro instruction. The LINK macro instruction in Figure 25 can now 
be written. Note that the DE operand refers to the name field, not the 
list description field, of the directory entry. 

Using CALL or Branch and Link 

You can save time by passing control to a load module without using 
the control program. Passing control without using the control program 
is performed as follows. Issue a LOAD macro instruction to obtain a 
copy of the load module, preceded by a BLDL macro instruction if you can 
shorten the search time by using it. The control program returns the 
address of the entry point to register 0 and the length in register 1. 
Load this address into register 15. The linkage requirements are the 
same when passing control between load modules as when passing control 
between control sections in the same load module: register 13 must con- 
tain a save area address, register 14 must contain the return address, 
and register 1 is used to pass parameters in a parameter list- A branch 
instruction, a branch and link instruction, or a CALL macro instruction 
can be used to pass control, using register 15. The return will be made 
directly to your program. 

Note: When control is passed to a load module without using the control 
program, you must check the load module attributes and current status of 
the copy yourself, and you must check the status in all succeeding uses 
of that load module during the job step, even when the control program 

is used to pass control. 

The reason you have to keep track of the usability of the load module 
has been discussed previously: you are not allowing the control program 
to determine whether you can use a particular copy of the load module. 
The following paragraphs discuss your responsibilities when using load 
modules with various attributes. You must always know what the reusabi- 
lity attribute of the load module is . If you do not know, you should 
not attempt to pass control yourself. 

If the load module is reenterable, one copy of the load module is all 
that is ever required for a job step. You do not have to determine the 
status of the copy; it can always be used. The best way to pass control 
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is to use a CALL macro instruction or a branch or branch and link 
instxuction. 



If the load module is serially reusable, one use of the copy must be 
completed before the next use begins, if your job step consists of only 
one task, preventing simultaneous use of the same copy involves making 
sure that the logic of your program does not require a second use of the 
same load module before completion of the first use. An exit routine 
must not require the use of a serially reusable load module also 
required in the main program. 



Preventing simultaneous use of the same copy when you have more than 
one task in the job step requires more effort on your part. You must 
still be sure that the logic of the program for each task does not 
require a second use of the same load module before completion of the 
first use. You must also be sure that no more than one task requires 
the uise of the same copy of the load module at one time; the ENQ macro 
instruction can be used for this purpose. Properly used, the ElSlQ macro 
instruction prevents the use of a serially reusable resource, in this 
case a load module, by more than one task at a time. Refer to "Resource 
control" for a complete discussion Of the ENQ macro instruction. A con- 
ditipnal ENQ macro instruction can also be used to check for simul- 
taneous use of a serially reusable resource within one task. 



If the load module is nonreusable, each copy can only be used once; 
you must be sure that you use a new copy each time you require the load 
module. You can ensure that you always get a new copy by using a LINK 
macro instruction or by doing as follows: 

1. Issue a LOAD macro instruction before you pass control. 

2. Pass control using a branch or a branch and link instruction or a 
CALL macro instruction only. 

3. Issue a DELETE macro instruction as soon as you are through with 
the copy. 



How Control is Returned 

The return of control between load modules is the same as return of 
control between two control sections in the same load module. The pro- 
gram in the load module returning control is responsible for restoring 
registers 2-14, possibly loading a return code in register 15, and pas- 
sing control using the address in register 14. The program in the load 
module to which control is returned can expect registers 2-13 to be 
unchanged, register 14 to contain the return address, and optionally, 
the register 15 to contain a return code. Control can be returned using 
a branch instruction or the RETURN macro instruction. If control was 
passed without using the control program, control returns directly to 
the calling program. However, if control was originally passed using 
the control program, control returns first to the control program, then 
to the calling program. 

The action taken by the control program is as follows, when control 
was passed using a LINK or ATTACH macro instruction, the responsibility 
count was increased by one for the copy of the load module to which con- 
trol was passed to ensure that the copy would be in virtual storage as 
long as it was required. The return of control indicates to the control 
program that this use of the copy is completed, and so the responsibili- 
ty count is decreased by one. The virtual storage area containing the 
copy is made available when the responsibility count reaches zero. 
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PASSING CONTROL WITHOUT RETURN 

The XCTL macro instruction is used to pass control between load 
modules when no return of control is required. You can also pass con- 
trol using a branch instruction; however, when you pass control in this 
manner, you must protect against multiple uses of nonreusable or serial- 
ly reusable modules. The following paragraphs discuss the requirements 
for passing control without return in each case. 

Passing Control Using a Branch Instruction 

The same requirements and procedures for protecting against reuse of 
a nonreusable copy of a load module apply when passing control without 
return as were stated under "Passing Control With Return." The proce- 
dures for passing control are as follows. 

A LOAD macro instruction should be issued to obtain a copy of the 
load module. The entry address returned in register 0 is loaded into 
register 15. The linkage requirements are the same when passing control 
between load modules as vhen passing control between control sections in 
the same load module; register 13 must be reloaded with the old save 
area address, then registers 14 and 2-12 restored from that old save 
area. Register 1 is used to pass parameters in a parameter list. A 
branch instruction is issued to pass control to the address in register 
15. 

Note ; Mixing branch instructions and XCTL macro instructions is hazar- 
dous. The next topic explains why. 

Using the XCTL Macro Instruction 

The XCTL macro instruction, in addition to being used to pass con- 
trol, is used to indicate to the control program that this use of the 
load module containing the XCTL macro instruction is completed. Because 
control is not to be returned, the address of the old save area must be 
reloaded into register 13. The return address must be loaded into 
register lU from the old save area, as must the contents of registers 
2-12. The XCTL macro instruction can be written to request the loading 
of registers 2-12, or you can do it yourself. If you restore all regis- 
ters yourself, do not use the EP parameter. This creates an inline 
parameter list that can only be addressed using your base register, and 
your base register is no longer valid. If EP is used, you must have 
XCTL restore the base register for you. 

When using the XCTL macro instruction, you pass parameters in a para- 
meter list, with the address of the list in register 1. In this case, 
however, the parameter list (or the paraumeter data) must be established 
in a portion of virtual storage outside the current load module contain- 
ing the XCTL macro instruction. This is because the copy of the current 
load module may be deleted before the called load module can use the 
parameters, as explained in more detail below. 

The XCTL macro instruction is similar to the LINK macro instruction 
in the method used to pass control: control is passed by way of the 
control program using a control program parameter list. The control 
program loads a copy of the load module, if necessary, loads the entry 
address in register 15, saves the address passed in register 14, and 
passes control to the address in register 15. The control program adds 
one to the responsibility count for the copy of the load module to which 
control is to be passed and subtracts one from the responsibility count 
for the current load module. The current load module in this case is 
the load niodule last given control using the control program in the per- 
formance cff the active task. If you have been passing control between 
load modules without using the control program, chances are the respon- 
sibility qount will be lowered for the wrong load module copy. And 
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remember, when the responsibiiit.y count of a copy reaches zerb, that 
copy may be deleted, causing unpredictable results if you try to return 
control to it. 

Figure 26 shows how this could ha£>p(eh. Control is given to load 
module A, which passes control to load module B (step 1) using a LOAD 
macro instruction and a branch and link instruction. Register 14 at 
this time contains the address of the instruction following the branch 
and link. BOad module B then is executed, independently of how control 
was passed, and issues an XCTL macro instruction when it is finished 
(step 2) to pass control to load module C. The control program^ taiowing 
only of load module A, lowers the responsibility cdunt of A by one, 
resulting in its deletion. Load module C is executed and returns to the 
address which used to follow the branch and link instru<:;tion. Step 3 of 
Figure 26 indicates the result. 

Two methods are available for ensuring that the proper responsibility 
count is lowered. One way is to always use the control program to pass 
control with or without return. The other method is to use only LOAD 
and DELETE macro instructions to determine whether or not a copy of a 
load module should remain in virtual storage. 
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Figure 26. Misusing control program facilities causes unpredictable 
results 
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ADDITIONAL ENTRY POINTS 



Through the use of linkage editor facilities you can specify as many 
as 17 different names (a member name and 16 aliases) and associated 
entry points within a load module. It is only through the use of the 
member name or the aliases that a copy of the load module can be brought 
into virtual storage. Once a copy has been brought into virtual 
storage, however, additional entry points can be provided for the load 
module, subject to this restriction. The load module copy to which the 
entry point is to be added roust be one of the following: 

• A copy which satisfied the requirements of a LOAD macro instruction 
issued during the Scume task 

• The copy of the load module most recently given control through the 
control program in performance of the same task 

The entry point is added through the use of the IDENTIFY macro 
instruction. An IDENTIFY macro instruction can be issued by any program 
in the job step except by asynchronous exit routines established using 
other supervisor macro instructions. In VSl, an IDENTIFY macro instruc- 
tion cannot be issued when the load module is given control at an entry 
point that was added by an IDENTIFY macro instruction. 

When you use the IDENTIFY macro instruction, you specify the name to 
be used to identify the entry point, and the virtual storage address of 
the entry point in the copy of the load module. The address must be 
within a copy of a load module that meets the requirements listed above; 
if it is not, the entry point will not be added, and you will be given a 
return code of OC (hexadecimal) . The name can be any valid symbol of up 
to eight characters, and does not have to correspond to a name or symbol 
within the load module. The name must not be the same as any other name 
used to identify any load module available to the control program; dupl- 
icate names cause errors- The control program checks the names of all 
load modules in the link pack area, the job pack area, and the 
partition/region of the job step when you issue an IDENTIFY macro 
instruction, and provides a return code of 08 if a duplicate is found. 
You are responsible for not duplicating a member name or an alias in any 
of the libraries. 

In VSl , the added entry point can be used only in an ATTACH macro 
instruction. The added entry point is available for as long as the copy 
is retained in virtual storage. Proper task synchronization is required 
when using an added entry point in the performance of a task which has 
not directly requested the associated copy of the load module; the load 
module may otherwise be deleted before the use is complete. The added 
entry point is treated as an entry point to a reenterable load module by 
the control program, regardless of the actual module attributes of the 
load module. You must guard against reuse of nonreusable coding. 



ENTRY POINT AND CALLING SEQUENCE IDENTIFIERS AS DEBUGGING AIDS 

An entry point identifier is a character string of up to 70 charac- 
ters which can be specified in a SAVE macro instruction. The character 
string is created as part of the SAVE macro instruction expansion. The 
dump program uses the calling sequence identifier and the entry point 
identifier as shown in the VSl Debugging Guide . 

A calling sequence identifier is a 16-bit binary number which can be 
specified in a CALL or a LINK macro instruction. When coded in a CALL 
or a LINK macro instruction, the calling sequence identifier is located 
in the two low-order bytes of the fullword at the return address. The 
high-order two bytes of the fullword form a NOP instruction. 
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CHAPTER 5; RESOURCE CONTROL 



TASK SYNCHRONIZATION 

Some plahriingi oil your part i 3 required to deteirmine what portions of 
one task are dependent on the completions of portions of all other 
tasks. The POST macro instruction is used to signal completion of an 
event; the WAIT macro instruction is used to indicate that a task cannot 
proceed until one or more events have occurred. An event control block 
is used with the WAIT and POST macro instructions; it is a fullword on a 
full word boundary, as shown in Figure 27. 

An event control block is also used when the ECB operand is coded in 
an ATTACH macro instruction. In this case the control program issues 
the POST macro instruction for the event (subtask termination). Either 
the 2U-bit (bits 8 to 31) return code in register 15 (if the task com- 
pleted normally) or the completion code specified in the ABEND macro 
instruction (if the task was abnormally terminated) is placed in the 
event control block as shown in Figure 27. The originating task can 
issue a WAIT macro instruction specifying the event control block; the 
task will not regain control until after the event has taken place and 
the event control block is posted (except if an asynchronous event 
occurs, for example, timer expiration) . 

When an event control block is originally created, bits 0 (wait bit) 
and 1 (post bit) must be set to zero. An event control block can be 
reused; if it is reused, bits 0 and 1 must be set to zero before either 
the WAIT or POST macro instruction can be used. If, however, the bits 
are set to zero before the ECB has been posted, any task waiting for 
that ECB to be posted will remain in the wait state. When a WAIT macro 
instruction is issued, bit 0 of the associated event control block is 
set to 1. When a POST macro instruction is issued, bit 1 of the asso- 
ciated event control block is set to 1 and bit 0 is set to 0. 

A WAIT macro instruction can specify more than one eVent by specify- 
ing more than one event control block. (Only one WAIT macro instruction 
can refer to an event control block at one time, however.) If more than 
one event control block is specified in a WAIT macro instruction, the 
WAIT macro instruction can also specify that all or only some of the 
events must occur before the task is taken out of the wait condition. 
When a sufficient number of events have taken place (event control 
blocks have been posted) to satisfy the number of events indicated in 
the WAIT macro instruction, the task is taken out of the wait condition. 



USING A SERIALLY REUSABLE RESOPRCE 

When one or more users of a serially reusable resource modify the 
resource, simultaneous use must be prevented. Consider a data area in 
virtual storage that is being used by programs associated with several 
tasks of a job step. Some of the users are only reading records in the 
data area; since they are not changing the records, their use of the 
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data area can be simultaneous. Other users of the data area, however, 
are reading, updating, and replacing records in the data area. Each of 
these users must acquire, update, and replace records one at a time, not 
simultaneously. In addition, none of the users that are only reading 
the records wish to use a record that another user is updating until 
after the record has been replaced. This illustrates why special care 
must be taken with serially reusable resources. 

For all of the uses of the serially reusable resource made during the 
performance of a single task, you roust prevent incorrect use of the 
resource yourself - You must make sure that the logic of your program 
does not require the second use of the resource before completion of the 
first use. Be especially careful when using a serially reusable 
resource in an exit routine; since exit routines are given control asyn- 
chronously from the standpoint of your program logic, the exit routine 
could obtain a resource already in use by the main program. For the 
uses of the serially reusable resource by more than one task, the ENQ 
macro instruction is provided to ensure that the resource is used seri- 
ally. The ENQ macro instruction cannot be used to prevent simultaneous 
use of the resource within a single task. It can only be used to test 
for simultaneous use within one task. 

The ENQ macro instruction requests the control progreum to assign con- 
trol of a resource to the active task. The control prograim determines 
the status of the resource, and either grants the request by returning 
control to the active task or delays assignment of control by placing 
the active task in the wait condition. When the status of the resource 
changes so that control can be given to a waiting task, the task is 
taken out of the wait condition and placed in the ready condition. The 
use of the ENQ macro instruction is discussed in the following 
paragraphs . 



NAMING THE RESOURCE 

You represent the resource in the ENQ macro instruction by two names 
known as the qname and the rnaine . These naumes may or may not have any 
relation to the actual name of the resource. The control program does 
not associate the name with the actual resource; it merely processes 
requests having the same qname and mame on a first- in, first-out basis. 
It is up to you to associate the names with the actual resource. It is 
up to all users of the resource to use qname and rname to represent the 
same resource. The control program treats requests having different 
qname and rname combinations as requests for different resources. 
Because the actual resource is not identified by the control program, it 
is possible to use the resource without issuing an ENQ macro instruction 
requesting it. If this happens, the control program cannot provide any 
protection. 

If the resource is used only in the performance of tasks in your job 
step, you can assign the qnarnie and rname combination. You should, in 
this case, code the STEP operand in the ENQ macro instructions that 
request the resource, indicating that the resource is used only in that 
job step. The control program adds the job step identifier to the rname 
so that duplicate qname and rname combinations are not used unintention- 
ally in different job steps. If the resource is available to any job 
step in the system, the qname and rname combination must be agreed upon 
by all users. The SYSTEM operand should be coded in each ENQ macro 
instruction requesting one of these resources. 

When selecting a qname for the resource, do not use SYS as the first 
three characters; qnames used by the control program start with SYS, and 
you might accidentally duplicate one of these. 
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EXCLUSIVE AND SHARED REQUESTS 



You can request exclusive or shared control of the resources for a 
task by coding either E or S in the ENQ macro instruction. If this use 
of the resource will result in modification of the resource, you must 
request exclusive control. If you are requesting use of a serially 
reusable load module and passing control yourself, you must request 
exclusive control, since that program modifies itself during execution. 
If you are updating a record in a data area, you must request exclusive 
control. If you are only reading a record, and you will not change the 
record, you can request shared control. 

In order to protect any user of a serially reusable resource, all 
users must request exclusive or shared control on this basis: When a 
task is given control of a resource in response to an exclusive request, 
no other task will be given simultaneous control of the resource. When 
a task is given control of a resource in response to a shared request, 
control will be given to other tasks simultaneously only in response to 
other requests for shared control, never in response to requests for 
exclusive control. A request for shared control will protect against 
modification of the resource by another task only if the above rules are 
followed. 

PROCESSING THE REQUEST 

The control program constructs a list for each qname and rname combi- 
nation it receives in an ENQ macro instruction, and enters a request in 
the list for the task which is active when the ENQ macro instruction is 
issued- The request is entered in an existing list when the control 
progrsun receives a request specifying a qname and rname combination for 
which a list exists; if no list exists for that qname and rname combina- 
tion, a new list is built. The requests are placed on the list in the 
order they are received by the control program; the priority of the task 
has no effect in this case. Control of the resource is allocated to a 
task according to two factors: 

• The position on the list of the task's request. 

• The exclusive control or shared control requirements of the request 
which caused the entry to be added to the list. 

Figure 28 shows the status of a list built for a very popular qname 
and rname combination. The S or E next to the entry indicates that the 
request was for shared or exclusive control. The task represented by 
the first entry on the list is always given control of the resource, so 
the task represented by ENTRYl (Figure 28, Step 1) is assigned the 
resource. The request which established ENTRY2 was for exclusive con- 
trol, so the corresponding task is placed in the wait condition, along 
with the tasks represented by all the other entries in the list. 



ENTRYl (S) 



ENTRY2 (E) 



ENTRY3 (S) 



ENTRY4 (S) 



ENTRY5 (E) 



ENTRY6 (S) 
Step 1 



ENTRY2 (E) 



ENTRY3 (S) 



ENTRY4 (S) 



ENTRY5 (E) 



ENTRY6 (S) 
Step 2 



ENTRY3 (S) 



ENTRY4 (S) 



ENTRY5 (E) 



ENTRY6 (5) 
Step 3 



Figure 28. ENG macro instruction processing 
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Eventually, control of the resource is released for the task repre- 
sented by ENTRYl, and the entry is removed from the list. As shown in 
Fiqure 28, Step 2, ENTRY2 is now first on the list, and the correspond- 
ing task is assigned control of the resource. Because the request which 
established ENTRy2 was for exclusive control, the tasks represented by 
all the other entries in the list are kept in the wait condition. 

Figure 28, Step 3, shows the status of the list after control of the 
resource is released for the task represented by ENTRY2. Because ENTRYa 
is now at the top of the list, the task represented by ENTRY3 is given 
control of the resource. ENTRY3 indicates that the resource can be 
shared, and, because ENTRY4 also indicates that the resource can be 
shared, ENTRY4 is also given control of the resource. In this case, the 
task represented by ENTRY5 will not be given control of the resource 
until control has been released for both the tasks represented by ENTRY3 
and ENTRY4. 



The following general rules are used by the control program: 

• A task represented by the first entry in the list is always given 
control of the resource. 

• If the request is for exclusive control, the task is not given con- 
trol of the resource until its request is the first entry in the 
list. 

• If the request is for shared control, the task is given control 
either when its request is first in the list or when all the entries 
before it in the list also indicate a shared request. 

• If the request is for several resources, the task is given control 
when all of the entries for an exclusive request are first in the 
list and all of the entries for a shared request are either first in 
the list or are preceded only by entries for other shared requests. 



USING ENQ AND DEQ 

Proper use of the ENQ and DEQ macro instructions is required to avoid 
duplicate requests, to avoid tying up the resource, and to avoid inter- 
locking the system. Guides to using them properly are given in the fol- 
lowing paragraphs. 



Duplicate Requests for a Resource 

A duplicate request occurs when an ENQ macro instruction is issued to 
request a resource and a task has already been assigned control of that 
resource. If the second request results in a second entry on the list, 
the control program recognizes the contradiction and refuses to place 
the task in the ready condition (for the first request) and in the wait 
condition (for the second request) simultaneously. The second request 
results in abnormal termination of the task. You must design your pro- 
gram to ensure that a second request for a resource is never issued 
until control of the resource is released for the first use. Again, be 
especially careful when using an ENQ macro instruction in an exit 
routine. 



Releasing the Resource 

The DEQ macro instruction is used to release a serially reusable 
resource assigned to a task through the use of an ENQ macro instruction. 
The task mjust be in control of the resource. A resource cannot be 
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released if the task does not have control. As you have seen* it is 
possible for many tasks to be placed in the wait condition while one 
task is assigned control of the resource. This may reduce the amount of 
work being done by the system.^ Issue a DEQ macro instruction as soon as 
possible to release the resource, so that other tasks can be performed. 
If a task returns control to the control program without releasing a 
resource, the resource is released automatically. 

Conditional and Unconditional Requests 

The normal use of the ENQ cuid DEQ macro instruction is to make uncon- 
ditional requests, and these are the only requests that have been consi- 
dered to this point. As you have seen, abnormal termination of the task 
occurs when two ENQ macro instructions are issued for the same resource 
in performance of the same task, without an intervening DEQ macro 
instruction. Abnormal termination also occurs if a DEQ macro instruc- 
tion is issued in a task that has not been assigned control of the 
resource. Both of these abnormal termination conditions can be avoided 
either by careful program design or through the use of the RET operand 
in the ENQ and DEQ macro instructions. The RET operand (RET=TEST, RET= 
USE, RET=CHNG, and RET=HAVE for ENQ; RET=HAVE for DEQ) indicates a con- 
ditional request for or release of a resource. 



RET=TEST is used to test the status of the list for the correspondihg 
qname and rname combination. An entry is never made in the list when 
RET=TEST is coded. Instead, a return code is provided indicating the 
status of the list at the time the request was made. A return code of 8 
roecuis the task is queued and has control of the resource. A return code 
of 12 means the resource is permanently unavailable. A return code of 
20 means the task is queued but does not have control of the resource. 
A return code of 4 indicates the task would have been placed in the wait 
condition if the request had been unconditional. A return code of 0 
indicates the task would have been given immediate control of the 
resource if the request had been unconditional. RET=TEST is most useful 
for determining if the task has already been assigned control of the 
resource. It is less useful for determining the status of the list and 
to take action based on that status. In the interval between the time 
the control program checks the status and the time your program checks 
the return code and issues another ENQ macro instruction, another task 
could have been made active, and the status of the list could have been 
changed. 



RET=USE indicates to the control program that the active task is to 
be assigned control of the resource only if the resource is immediately 
available. A return code of 0 indicates that the request was put on the 
list and the task was assigned control of the resource. A return code 
of U indicates that the task would have been placed in the wait condi- 
tion if the request had been unconditional. A return code of 8 means 
the task is queued and has control of the resource. A return code of 12 
means the resource is permanently unavailable. A return code of 20 
means the task is queued but does not have control of the resource. The 
request is not put on the list if any return code other than 0 is given. 
RET=USE can be best used when there is other processing that can be done 
without using the resource. You do not want to wait for the resource if 
there is other work that you can do. 



RET=CHNG indicates to the control program that the caller wishes to 
have exclusive control of a resource which he has already requested- A 
return code of 0 indicates that the resource was available and was 
assigned to the exclusive control of the caller. Either the caller had 
already requested exclusive control, or the requested change from shared 
to exclusive control was honored. A return code of U indicates that the 



42 



requested change in attribute cannot be honored, because the caller is 
currently sharing the resource with another user. A return code of 8 
indicates that the user was not queued to receive control of the 
resource when he requested the attribute change. A return code of 12 
means the resource is permanently unavailable. Although this is an 
error condition, control is returned to the user. 

RET=HAVE is used in both the ENQ and DEQ macro instructions. An ENQ 
macro instruction is treated as a normal request for control unless a 
request from the same task already exists. A return code of 8 means the 
task is queued and has control of the resource. A return code of 12 
means the resource is permanently unavailable. A return code of 20 
means the task is queued but does not have control of the resource. A 
return code of 0 indicates that the task was assigned control of the 
resource. A DEQ macro instruction is processed as a normal request to 
release a resource unless the 'task does not have control of the 
resource. A return code of 0 indicates that the resource has been 
released. A return coe of 8 indicates that the task did not have an 
entry for the resource (although the task may be in the wait condition 
because of a request for the resource) . RET=HAVE can be used to good 
advantage in an exit routine to avoid abnormal termination. 



Avoiding Interlock 



An interlock condition arises when two tasks are waiting for each 
others completion, yet neither task can gain access to the resource 
necessary for its completion. An example of an interlock is shown in 
Figure 29. Task A has exclusive access to resource M, and higher- 
priority task B has exclusive access to resource N. Task B is placed in 
a wait condition when it requests exclusive access to resource M because 
M is accessible only by task A. The interlock becomes complete when 
task A requests exclusive access to resource N, because N is accessible 
only by Task B. The same interlock would have occurred if task B issued 
a single request for multiple resources W and N prior to task A's second 
request. The interlock would not have occurred if both tasks had issued 
single requests for multiple resources. Other tasks requiring either of 
the resources are also in a wait condition because of the interlock, 
although in this case they did not contribute to the conditions that 
caused the interlock. 



The above example involving two tasks and two resources is a simple 
example of an interlock. The example could be expanded to cover many 
tasks and many resources- It is imperative that interlocks be avoided. 
The following procedures indicate some ways of preventing interlocks. 

• Do not request resources that are not immediately required. If you 
can use the serially reusable resources one at a time, you should 
request them one at a time and release one before requesting the 
next . 



Task A 



ENQ (M,A,E,8,SyST£M) 



Task B 



ENQ (N,B,E, 8, SYSTEM) 



ENQ (M, A, £,8, SYSTEM) 



1 



ENQ (N,B,£, 8, SYSTEM) 



Figure 29. Interlock condition 
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I ENQ (NAME1ADD,NAME2ADD,E, 8, SYSTEM) 

I ENQ (NAME3ADD,NAME4ADD,E,10,SySTEN) 

Figure 30. Two requests for two resources 



r 1 

I ENQ (NAME1ADD,NAME2ADD,E, 8, SYSTEM, NAME3ADD,NAMEaADD,E, 10, SYSTEM) | 

L-.; . . . . . . . J 

Figure 31. One request for two resources 



• Share resources as much as possible. If the requests in the lists 
shown in Figure 29 had been for shared resources, there would have 
been no interlock. This does not icean you should share a resource 
that you will modify. It does mean that you should analyze your 
requirements for the resources carefully, and not request exclusive 
control when shared control would suffice. 

• The ENQ macro instruction can be written to request control of more 
than one resource at a time. The requesting program is placed in a 
wait state until all of the requested resources are available. 
Those resources not being used by any other program immediately 
become exclusively available to the waiting program and are unavail- 
able to any other programs that may request them. For example, 
instead of coding the two ENQ macro instructions shown in Figure 30 , 
the one ENQ macro instruction shown in Figure 31 could be coded. If 
all requests were made in this manner, the interlock shown in Figure 
29 would be avoided. All of the requests from one task wOuld be 
processed before any of the requests from the second task. The DEQ 
macro instruction should be written in the same manner to release 
the entire set of resources at once. 



• If the use of one resource always depends on the use of a second 
resouce, then the pair of resources can be defined as one resource 
in the ENQ and DEQ macro instructions. This procedure can be' used 
for any number of resources that are always used in combination. 
There would be no protection of the resources if they are also 
requested independently, however. The request would always have to 
be for the set of resources. 

• If there are many users of a group of resources and some of the 
users require control of a second resource while retaining control 
of the first resource, it is still possible to avoid interlocks. In 
this case the order in which control of the resources is requested 
should be the same for each user. > For instance, if resources A, B, 
and C are required in the performance of many tasks, the requests 
should always be made in the order of A, B, and C. An interlock 
situation will not develop, since requests for resource A will 
always precede requests for resource B. 

The above is not an exhaustive list of the procedures to be used to 
avoid an interlock. You could also make repeated requests for control 
specifying the RET=USE operand, which would prevent the task from being 
placed in the wait condition; if no interlock was developing, of course, 
this would be a waste of execution time. The solution to the interlock 
problem in all cases requires the cooperation of all the users of the 
resources. 
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CHA PTER 6 ; INTE RRUPTI ON, TERMNATION, AND DUMPING SERVICES 



PROGRAM INTERRUPTI O N PROCESSING 

Some conditions encountered in a program cause a program interrup- 
tion. These conditions include incorrect operands and operand specifi- 
cations, as well as exceptional results, and are known generally as pro- 
qram exceptions . For certain exceptions (fixed-point and decimal over- 
flow, exponent underflow and significance), interruptions can be dis- 
abled by setting the corresponding bits in the program status word to 
zero. 

When a task becomes active for the first time, all program interrup- 
tions that can be disabled are disabled, and a standard control program 
exit routine, included when the system was generated, is provided. This 
control program exit routine is given control when certain program 
interruptions occur; it issues an ABEND macro instruction specifying 
task abnormal termination and requesting a dump. By issuing the SPIE 
macro instruction, you can specify your own exit routine to be given 
control for one or more types of program exceptions. The macro instruc- 
tion specifies the address of the exit routine to be given control when 
specified program exceptions occur. If the SPIE macro instruction spe- 
cifies an exception for which the interruption has been disabled, the 
control program enables the interruption when the macro instruction is 
issued. 

The SPIE macro instruction can be issued by any program being 
executed in performance of the task. When the task is active, your exit 
routine receives control for all interruptions resulting from exceptions 
specified in the SPIE macro instruction unless the current routine for 
the task is operating in supervisor mode. For other program interrup- 
tions, control is given to the control program exit routine. Each suc- 
ceeding SPIE macro instruction completely overrides specifications in 
the previous macro instruction. 



PROGRAM INTERRUPTION CONTROL AREA 

The expansion of each standard or list form SPIE macro instruction 
contains a control program parameter list called the program interrup- 
tion control area (PICA). The PICA and another control program area 
called the program interruption element (PIE) contain the information 
that enables the control program to intercept user-specified program 
interruptions. Together, the PIE and the PICA associated with it are 
called the "SPIE environment." (The PIE is described later in this sec- 
tion.) The PICA, as shown in Figure 32, contains the new program mask 
for the interruption types that can be disabled, the address of the exit 
routine to be given control when one of the specified interruptions 
occurs, and a code for interruption types (exceptions) specified in the 
SPIE macro instruction. 

The control program maintains a pointer (in the PIE) to the PICA 
referred to by the last SPIE macro instruction executed. This PICA may 
have been created by the last SPIE (standard or list form) or may have 
been created previously and referred to by the last SPIE (execute form). 
Each program that issues a SPIE macro instruction, before returning con- 
trol to the calling program or passing control to another program by 
issuing ah XCTL macro instruction, must cause the control program to 
adjust the SPIE environment to the condition that existed or to elimin- 
ate the SPIE environment if one did not exist on entry to the program. 
When the standard or execute form of the SPIE macro instruction is 
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issued, the control program returns the address of the previous PICA in 
register 1. If no SPIE environinent existed when the program was 
entered, the control program returns zeros in register 1. 

The effect of the last SPIE macro instruction is canceled by issuing 
a SPIE macro instruction with no operands. This action does not reesta- 
blish the effect of the previous SPIE; it does create a new PICA that 
contains zeros, thus indicating that nc user exit routine is to process 
interruptions. Any previous SPIE environment may be reestablished, 
regardless of the number or type of subsequent SPIE macro instructions 
issued, by using the execute form of the SPIE macro instruction specify- 
ing the appropriate value that had been returned in register 1 by the 
control program. If a PICA address is specified (as opposed to zeros) , 
the PICA must still be valid (not overlaid). The SPIE environment will 
be eliminated by specifying zeros as the PICA address. 



DISPLACEMENT 
(Bytes) 0 



1 



I Pro- 
0000 I gram 
I Mask 



Exit Routine Address 



I nterruption 
Type 



Figure 32. Program interruption control area 



Figure 33 shows how to restore a previous PICA. The first SPIE macro 
instruction designates an exit routine called FIXUP that is to be given 
control if fixed- point overflow occurs. The address returned in regist- 
er 1 is stored in the fullword called HOID. At the end of the program, 
the execute form of the SPIE macro instruction is used to restore the 
previous PICA. 



PROGRAM INTERRUPTION ELEMENT 

At the first execution of a SPIE macro instruction during the perfor- 
mance of a task, the control program creates a 32 -byte program interrup- 
tion element (PIE) in the virtual storage area assigned to the job step 
and, in VSl, a 32- byte work area in the protected queue area for the 
program check handler. Because the PIE is freed when the SPIE environ- 
ment is eliminated (by specifying a PICA address of zero in the execute 
form of a SPIE macro instruction), a PIE will also be created whenever a 
SPIE macro instruction is issued and no PIE exists. The format of the 
PIE is shown in Figure 34. 

The PICA address in the program interruption element is the address 
of the program interruption control area used in the last execution of a 
SPIE macro instruction for the task. When control is passed to the rou- 
tine indicated in the PICA, the old program status word contains the 
interruption code in bits 16-31; these bits can be tested to determine 
the cause of the program interruption. The contents of registers lU, 
15, 0, i, and 2 at the time of the interruption are stored by the con- 
trol program as indicated. 



REGISTER CONTENTS UPON ENTRY TO USER'S EXIT ROUTINE 

When control is passed to the designated exit routine, the register 
contents are as follows: 

Register 0 ; Internal control program information. 
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Register 1 : Address of the program interruption element for the task 
that caused the interruption. 

Registers 2-12 : Same as when the program interruption occurred. 

Register 13 : Address of the save area for the main program. The exit 
routine must not use this save area. 

Register 14 : Return address (to the control program). 
Register 15 ; Address of the exit routine. 



j SPIE FIXUP, (8) Privide exit routine for fixed-point overflow! 

1 ST 1,H0LD Save address returned in register 1 j 

I ... I 

I L 5, HOLD Reload returned address | 

I SPIE MF=(E,(5)) Use execute form and old PICA address | 

I ... I 

I HOLD DC F*0* I 

L J 

Figure 33. Using the SPIE macro instruction 
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Old Program 
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(Interruption Codes) 



Register 14 



Register 15 



Register 0 



Register 1 



Register 2 



Figure 34. Program interruption element 



The exit routine must be in virtual storage when it is required, and 
must return control to the control program using the address passed in 
register 14. The control program restores registers 14, 15, 0, 1, and 2 
from the program interruption element after control is returned, but 
does not restore the contents of registers 3-13. If a program interrup- 
tion occurs when the program interruption exit routine is in control, 
the control program exit routine is given control. 

To determine which type of interruption occurred, the exit routine 
can test bits 28 through 31 of the old program status word (OPSW) in the 
program interruption element. The routine can then take corrective 
action or can simply ignore the exceptional condition. 

The exit routine can alter the contents of the registers when control 
is returned to the interrupted program. For registers 3 through 13, the 
routine alters the contents of the actual registers. For registers 14 
through 2, the routine alters the contents of the register save area in 
the program interruption element, because the control program reloads 
these registers from this area when it returns control to the inter- 
rupted program. The exit routine can also alter the last four bytes of 
the OPSW in the program interruption element. By changing the OPSW, the 
routine can select any return point in the interrupted program. 



HANDLING ABNORMAL CONDITIONS 

It is not possible to provide procedures for all possible conditions 
which can occur during the execution of a program. You should, of 
course, be sure that you can process all valid data, and that your pro- 
gram satisfies all the requirements of the problem. The more general 
you make the program, the greater the number of additional routines you 
will require to handle special cases. But you will not be able to pro- 
vide routines to detect and correct all of the special or abnormal con- 
ditions that can occur. 
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The 0Qfrtxol iJirogr^Hn does a ^>eat deal of checKing for abnormal cxjndi- 
tions. 1^ stamdard prograro infceriin:igE^iOai routine is prroid-ded detecl: 
and process errors such as protection violations or addressing errors. 
The data management and supervisor routines provide some error checking 
facilities to ensure that, based on the information you have provided, 
only valid data is being proofs sned, and that no requests with conflict- 
ing requiremegats :have iaeen made^ For the a^bnormal conditions that can 
;l»QSSibly be ODrrected, control is 3?etumed to your program with a return 
code indicating the proba3bie soutcce of the error. For conditions that 
indicate that further processing would result in degradation of the sys- 
tem or destruction of existing data,, the control program abnormal ter- 
mnation routine is giieten control. 

There will toe abnorma.! conditions unigue to your program, of course, 
that tlie coiKtr©! f^gr^am camai&t detect* Figure 35 is an example of one 
of these« aaie r^outine ishc^in ±n Figure 35 checks a control f ield in an 
input parameter list to determne which function the program is to per- 
form. Only characters between 1 and 4 are valid in the control field. 
The presence of any other character is invalid, but the routine must be 
prepared to detect and handle these characters. The routine should ind- 
icate its inal)ility to continue processing by returning control to the 
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Figure 35, 33etecting an abnormal condition 
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calling program with an error return code. The calling prograin should 
then try to interpret the return code and to recover front the error. If 
it cannot do so, the calling program should detach its incomplete sub- 
tasks, execute its usual termination procedures, and return control to 
its calling program, again with an error return code. This procedure 
may result in termination of all the tasks of a job step; if it does, 
the COND parameters of the JOB and EXEC statements may be used to deter- 
mine whether subsequent job steps should be executed. 

An alternative to this procedure is to pass control to the control 
program abnormal termination routine by issuing an ABEND macro instruc- 
tion. This alternative is simpler, but it offers less opportunity for 
error recovery and continued processing unless a STAE macro instruction, 
specifying a STAE exit routine address, is issued to override the ABEND. 
The use of STAE is discussed in the Planning and Use Guide . The abnorm- 
al termination facilities available through the use of the ABEND macro 
instruction are discussed below; an explanation of the facility to 
intercept abnormal termination through the STAE macro instruction is 
presented following the ABEND discussion. 

The position within the job step hierarchy of the task for which the 

ABEND macro instruction is issued determines the exact function of the 
abnormal termination routine. If an ABEND macro instruction is issued 
when the job step task (the highest level or only task) is active, or if 
the STEP operand is coded in an ABEND macro instruction issued during 
the performance of any task in the job step, all the tasks in the job 
step are terminated. An ABEND macro instruction (without a STEP 
operand) that is issued in performance of any task other than the job 
step task usually causes only that task and the subtasks of that task to 
be abnormally terminated. However, if the abnormal termination cannot 
be fulfilled as requested, it may be necessary for the control program 
to abnormally terminate the job step task. The most frequent cause of 
this is that the subtask does not have sufficient virtual storage for 
ABEND'S processing. ABEND "steals" virtual storage allocated to the job 
step task and needed by it to continue normal processing. The abnormal 
termination routine works in the same manner whether it is given control 
from the control program or a problem program. 

When a task is abnormally terminated, the control program performs 
the following functions: 

• Lowers the responsibility counts for the load modules brought into 
virtual storage during the performance of the task. 

• Releases the virtual storage subpools owned by the tasks. 

• Cancels the time interval if one had been established for the task. 

• Issues a CLOSE macro instruction for any data control blocks that 
were opened during the performance of the task- 

• Purges any outstanding input or output requests. 

• Cancels any requests for operator replies made using a WTOR macro 
instruction. 

• Cancels any requests for resources made using an ENQ macro 
instruction. 

If the job step is not to be terminated, the following action is 
taken: 

• The abnormal termination functions listed above are performed, 
starting with the lowest level task, for each of the subtasks of the 
task that was active when the ABEND macro instruction was issued. 
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• The completion code specified in the ABEND macro instruction is 
placed in the task control block of the active task (the task for 
which the ABEND macro instruction was issued) . 

• If the ECB operand was written in the ATTACH macro instruction 
issued to create the active task, the ECB is posted with the comple^ 
tion code specified in the ABEND macro instruction. 

• if the ETXR operand was written in the ATTACH macro instruction 
issued to create the active task, the end-of-task exit routine is 
3<dleduled to be given control when the originating task becomes 
active. 

• If neither the ECB nor ETXR operands were written when the ATTACH 
macro instruction was issued, a DETACH macro instruction is issued 
by the control program for the active task. 



If the job step is to be terminated, the following action is taken: 

• The abnormal termination functions listed above are performed, 
starting with the lowest level task, for all tasks in the job step. 
All virtual storage belonging to the job step is released. None of 
the end-of-task exit routines are given control, 

• The completion code specified in the ABEND macro instruction is 
written on the system output device. 

• Unless you specify otherwise in your job control statements, the 
remaining job steps in the job are skipped. However, the statements 
defining these steps are checked for proper syntax. 

It is possible to restart a job step that has been abnormally ter- 
minated. Restart can occur either at the beginning of the job step or 
at an internal checkpoint. A detailed discussion of checkpoint and 
restart appears in Checkpoint/Restart . 



DUMPING SERVICES 

There are three types of storage duirps produced by the operating 
system: 

• A dump obtained through use of the DUMP operand in the ABEND macro 
instruction. 

• A dump obtained through use of the SNAP macro instruction. 

• An SVC dump, produced in the event of a failure by a system routine. 

You can request a dump by using the ABEND or SNAP macro instruction. 
You caimot request the SVC dump — it is produced automatically by the 
system whenever a failure occurs in a system routine. 



ABEND AND SNAP DUI^S 

When the dump is requested using an ABEND macro instruction, no 
further processing is performed for the active task; use of the SNAP 
macro instruction allows the task to continue after the completion of 
the diamp. The control program usually request a dump for you when it 
issues an ABEND macro instruction. 
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The data set containing the dump can reside on any device which is 
supported by the basic sequential access method (BSAM) . The dump is 
placed in the data set described by the DD statement you provide. If a 
printer is selected the dump is printed immediately. However, if a 
direct access or tape device is designated, a separate job must be sche- 
duled to obtain a listing of the dump, and to release the space on the 
device. 

The format of the dump is shown in the publication VSl Debugging 
Guide . The entire dump shown in that publication is provided in an 
abnormal termination dump if a DD statement with a DD name of SYSABEND 
is provided; only the problem program areas and system control blocks 
associated with the problem program are dumped if a DD statement with a 
DD name of SYSUDUMP is provided. Use of the SNAP macro instruction 
allows you to request only selected portions of the entire dump for any 
task in the job step; the format of the portions selected is the same as 
the format of the same portions of an abnormal termination dump. 

When an abnormal termination dump is requested, the entdLre dump is 
provided for the active task, along with a dump of the control blocks 
and save area for each of the higher level tasks which are predecessors 
of the active task being terminated and for each of the subtasks of the 
active task. The control progrcim dump routine uses the addresses you 
stored in words 2 and 3 of each save area to follow the chain of save 
areas provided by each calling program in each task. If an ABEND macro 
instruction was issued when task Bl (Figure 8) was active, for example, 
a complete dump would be provided for task Bl. The control blocks and 
save areas for task B, task Bla, and the job step task would also be 
provided in separate dumps. 

To get a dump: 

• You must provide a DD statement for each job step in which a dump is 
requested. For an abnormal termination dump, the DD name must be 
SYSABEND or SYSUDUMP; for a SNAP macro instruction dump, the DD name 
must be any name except SYSABEND or SYSUDUMP. Figure 36 shows a set 
of job steps that include DD statements for ABEND dump data sets. 




Figure 36. Sample DD statements for an ABEND dump 
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• To obtain a dump ueing the SNAP macro instruction, you must provide 
a data control block and issue an OPEN macro instruction for the 
data set before any SNAP macro instructions are issued. The data 
control block must contain the following parameters: DSORG=PS, 
RBCFi^VBA, mcrn^, Bm§tZE^BB2, and LRECL=125. (The data control 
block is discussed in the Data Management Services manual.) If 
yourprograoi is to be processed by the loader, you should also issue 
a CliO&E foaucxo instruction jEor the SNAP data control block. 



INDICATIVE DOMP <VS1) 

You can obtalii an indicative dump, as shown in VSl Debugging Guide . 
This dixmp is provided iii response to a request for an abnormal termina- 
tion damp when either you did not provide a PD statement with the DD 
name sySAJBEND or SYSUPCW, or the control program entry for that DD sta- 
teiiient was destroyed. The indicative dump is printed on the system out- 
put device. 



SVC DUMP 

If a systesi routine fails, the system automatically supplies a dump 
of the contents of virtual storage. This dump, called the SVC dump, 
provides diagnostic information. The system writes the dump in the sys- 
tem data set SYSl.DUMP or in a tape volume at the device designated when 
the operating system was initially loaded. Use the HMDPRDMP service aid 
program to obtain a printout of the dump. A description of HWDPRDMP and 
the dump formats appear in the Service Aids publication. For guidance 
in using the dump, refer to the VS Debugging Guides . 
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CHAPTER 7; VIRTUAL STORAGE MANAGEMENT 



You obtain the use of the virtual storage area assigned to your job 
step through implicit and explicit requests for virtual storage. The 
use of a LINK macro instruction is an example of an implicit request; 
the control program allocates storage before bringing the load module 
into your job pack area. The use of the GETMAIN macro instruction is an 
explicit request for a certain number of bytes of virtual storage to be 
allocated to the active task. In addition to your requests for virtual 
storage, requests are made by the control program and data management 
routines for areas to contain some of the control blocks required to 
manage your tasks. * ' 



Note: If your job step is to be executed as a nonpageable (V=R) task, 
the REGION parameter value specified on the job or execute statement 
determines the amount of virtual (real) storage reserved for the job 

step. If you run out of storage because of a system failure, such as in 
a GETMAIN request, increase the REGION parameter size. 

The following paragraphs discuss some of the techniques that can be 
applied for efficient use of the virtual storage area reserved for your 
job step. These techniques apply as well to the data management por- 
tions of your programs. The specific data management storage allocation 
facilities are discussed in the Data Mauiaqement Services and Data Mana*- 
qement Macro Instructions publications; the principles discussed here 
provide the background you need to use these facilities. 



EXPLICIT REQUESTS FOR VIRTUAL STORAGE 

Virtual storage can be explicitly requested for the use of the active 
task by issuing a GETMAIN macro instruction. The virtual storage requ- 
est is satisfied by allocating to the active task a portion of the vir- 
tual storage area reserved for the job step. The virtual storage area 
is usually not set to zero when allocated (the storage is zeroed in VS2 
for the initial allocation of a page). 

You release virtual storage by issuing a FREEMAIN macro instruction. 
This does not release the area from control of the job step, but makes 
the area available to satisfy the requirements of additional requests 
for any task in the job step. The virtual storage assigned to a task is 
also given up to a different task in the same job step when the task 
terminates, except as indicated under "Subpool Handling." Releasing 
virtual storage for use by other job steps is discussed under "Relin- 
quishing Virtual Storage." 



Specifying the Size of the Area 

virtual storage areas are always allocated to the task in multiples 
of eight bytes and may begin on either a doubleword or page boundary. 
The request for virtual storage is given in terms of bytes; if the numb- 
er specified is not a multiple of eight, it is rounded to the next high- 
er multiple of eight. You can make repeated requests for a small number 
of bytes as you need the area or you can make one large request to com- 
pletely stitisfy the requirements of the task. There are two reasons for 
making one large request: it is the only way you can be sure of getting 
contiguous storage and avoid fragmenting your partition, and because you 
only make one request, the amount of control program overhead is less. 
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Types of Explicit Regues-bs 



There are tliree methods of explicitly requestin^g virtual storage 
using a GETNAIIii macro instruction. Each of the methods, which are desi- 
gnated by coding an associated character in the operand field of the 
GETMAIN macro instruction, has certain advantages, depending on the 
requirements of your progreun. The last two methods do not produce 
reenterable coding unless coded in the list and execute forms, as indi- 
cated in "tmplicit Requests." The methods are as follows: 



Register Type (R) ; Specifies a request for a single area of virtual 
storage of a specified length. The address of the area is returned in 
register 1. This type of request produces reenterable coding, because 
parameters are passed to the control prograan in registers, not in a 
parameter list. 



Element Type (E) ; Specifies a request for a single area of virtual 
storage of a specified length. The control program places the address 
of the allocated area in a fullword that you supply. 

Variable Type (V) ; Specifies a request for a single area of virtual 
storage vith a length between two values you specify. The control pro- 
gram attempts to allocate the maximum length you specify; if not enough 
storage. is available to allocate the maximimn length, the largest area 
with a length between the two values is allocated. The control program 
places the address of the area and the length allocated in two consecu- 
tive fullwords that you supply. 



In addition to the above methods of requesting virtual storage, you 
can designate the request as conditional or unconditional. (A register 
type request is always unconditional.) If the request is unconditional 
and sufficient virtual storage is not available to fill the request, the 
active task is abnormally terminated. If the request is conditional, 
however, and insufficient virtual storage is available, a return code of 
4 is provided in register 15; a return code of 0 is provided if the 
request was satisfied. 



An example of using the GETMAIN macro instruction is shown in Figure 
36. The example assumes a program that operates most efficiently with a 
work area of 16,000 bytes, with a fair degree of efficiency with 8,000 
bytes or more, inefficiently with less than 8,000 bytes. The program 
uses a reenterable load module having an entry name of REENTMOD, and 
will use it again later in the program; to save time, the load module 
was brought into the job pack area using a LOAD macro instruction so 
that it will be available when it is required* 



A conditional request for a single element of storage with a length 
of 16,000 bytes is requested in Figure 37. The return code in register 
15 is tested to determine if the storage is available; if the return 
code is 0 (the 16,000 bytes were allocated), control is passed to the 
processing routine. If sufficient storage is not available, an attempt 
to obtain more virtual storage is made by issuing a pELETE macro 
instruction to free the area occupied by the load module REENTMOp. A 
second GETMAIN macro instrfiction is issued, this time an unconditional 
request f or ax3t area between ftrOOO and 16»000 bytes in length, if the 
minimum size is not available, the task is abnormally terminated. If at 
least 4,000 bytes are available, the task can continue- The size of the 
area actually allocaited is determined^ and one of the two procedures 
(efficient or inefficient) is given control. 
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Figure 38. Releasing virtual storage 



Relinquishing Virtual Storage 

All storage obtained for your program by the GETMAIN macro instruc- 
tion is automatically freed by the control program when the job step 
terminates. Freeing storage in this manner requires no action on your 
part. 

When an area of virtual storage within your program no longer has 
meaningful or significant contents, you can make this storage available 
by issuing a PGRLSE macro instruction. The FGPLSE macro makes all real 
and external page storage wholly associated with the area of virtual 
address space specified available as shown in Figure 38. The address 
space remains intact, but its contents are forfeited. When the using 
program can discard the contents of a large virtual area (one or more 
complete pages) and reuse the address space without the necessity of 
paging operations, PGRLSE may improve operating efficiency. 

When you issue a FREEMAIN macro instruction, FREEMAIN does the equi- 
valent of ; PGRLSE for any resulting free page^ 
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Subpool Handling (In VSl Systems) 



Although sufcpools are not created in VSl systenis, it is convenient to 
call the partition itself "subpool 0." That is, all virtual storage 
available to the user in a partition is shared by all tasks active in 
that partition. 

User prcgrajns may request virtual storage f rore the partition by spe- 
cifying any subpool nuirber frofti 0 to 127 or ty specifying no number at 
all. Implied requests for storage, initiated when the ur^er executes an 
ATTACH, LINK, LOAD, or XCTL macro instruction, are recorded by the con- 
trol program in order for the storage to be freed during termination. 

Subpool Handling (In VS2 Systems) 

In an operating systen with VS2, sutpools of virtual storage are pro- 
vided to assist in virtual storage management and for coirmunications 
between tasks in the same job step- Because the use of subpools 
requires some knowledge of how the control program manages virtual 
storage, a discussion of virtual storage ccntrcl is presented here- 

VIRTUAL STORAGE COOTRQI : When the job step is given a region cf virtual 
Storage, all of the storage area available for your use within that 
region is unassigned. Subpools are created only when a GETNAIN macro 
instruction is issued designating a sufcpool number. If no subpool numb- 
er is designated, the virtual storage is allocated from subpool 0, which 
is created for the job step by the control program when the job- step 
task is initiated. 

Note : If virtual storage is allocated to a suttask by the user program 
while the system is being executed in the supervisor state or with a 
protection key of 0, no other task should free that virtual storage. If 
some other task does free that virtual storage, you get unpredictable 
results. 

For purposes of control and virtual storage protection, the control 
program considers all virtual storage within the region in terms of 
4096-byte blocks. These blocks are assigned to a subpool, and space 
within the blocks is allocated to a task by the control program when 
requests for virtual storage are made. When there is sufficient unallo- 
cated virtual storage within any block assigned to the designated sub- 
pool to fill a request, the virtual storage is allocated to the active 
task from that block. If there is insufficient unallocated virtual 
storage within any block assigned to the subpool, a new block (or 
blocks, deEending on the size of the request) is assigned to the sub- 
pool, and the storage is aXlacated to the active task.* The blocks 
assigned to a subpool are not necessarily contiguous unless they are 
assigned as a result of one request. Only blocks within the region 
reserved for the associated job step can be assigned to a subpcol. 

Figure 39 is a siinplified view of a virtual-storage region containing 
four U096-byte blocks of storage. All the requests are for virtual 
storage from subgool 0. The first reqyest from some task in the job 
step is for lOOfif bytes; the request satisfied from the block shown as 
Block A in the figure* The second req^iteslr, fbr 4000 bytes, is too large 
to be satisf ied f rom the untised portion of Block A, so the control pro^ 
gram assigns the next available blGck, Block B, to subpool 0, and allo- 
cates 4000 bytes from Block B to the active task. A third request is 
then received, this time for 2000 bytes. There is not sufficient una 1- 
loca-tedv cKrest remaKLning in Block B; Cljloisks are checked in the order first 
in,, f irst Qutljvv but tlier;e is ensowg^. aJsLea in Blqek A, so an additional 
2000 tey tejs; are alXacated: to the task from Block A« Because all tasks 
may shar^e smtopicf©!; 0, Re<piest 1 artd^ E^easpest 3 do not have to be made f rom 
the same task, even though the areas are contiguous and from the same 
4096 byte block. Request 4, for 6000 bytes, requires that the control 
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Figure 39. Virtual- storage control 



program allocate the area from 2 contiguous blocks which were previously 
unassigned. Block D and Block C. These blocks are assigned to subpool 
0. 

As indicated in the preceding example, it is possible for one 4096- 
byte block in subpool 0 to contain many small areas allocated to many 
different tasks in the job step, and it is possible that numerous blocks 
could be split lip in this manner. Areas acquired by a task other then 
the job-step task are not released automatically on task termination. 
Even if FREEMAIN macro instructions were issued for each of the small 
areas before a task terminated, the probable result would be that many 
small unused areas would exist within each block, while the control pro- 
gram would be continually assigning new blocks to satisfy new requests. 
To avoid this situation, you can define subpools for exclusive use by 
individual tasks. 



Any subpool can be used exclusively by a single task or shared by 
several tasks. Each time that you create a task, you can specify which 
subpools are to be shared. Unlike other subpools, sxibpool 0 is shared 
by a task and its subtask, unless you specify otherwise. When subpool 0 
is not shared, the control program creates a new subpool 0 for use by 
the subtask. As a result, both the task and its subtask can request 
storage from subpool 0, but both will not receive storage from the saune 
4 096- byte block. When the subtask terminates, its virtual storage areas 
in subpool 0 are released; since no other tasks share this subpool, com- 
plete 4096-byte blocks are made available for reallocation. 

When there is a need to share subpool 0, you can define other sub- 
pools for exclusive use by individual tasks. When you first request 
storage from a subpool other than subpool 0, the control program assigns 
a new 4096-byte block to that subpool, and allocates storage from that 
block. The task that is then active is assigned ownership of the sub- 
pool and, therefore, of the block. When additional requests are made by 
the same task for the same subpool, the requests are satisfied by allo- 
cating areas from that block and as many additional blocks as are 
required. If another task is active when a request is made with the 
same subpool number, the control program assigns a new block to a new 
subpool, allocates storage from the new block, and assigns ownership of 
the new subpool to the second task. 
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A task can specify subpools njiaabered from 0 to 127. FREEMAIN macro 
instructions can be issued to release any subpool except sub|)Ool 0, thus 
releasing complete U096-byte blocKs. When a task terminates, its 
unsbareiS subpoqls are released automatically. 

Owning and Storing ; A sybpopl is initially owned by the task that was 
active When" the sig^ was created. The subpool can be shared with 
other tasks, and ownership of the subpool can be assigned to other 
tasks. Two macro instructions are used in the handling of subpools: 
the GETfSAIN macro instruction and the ATTACH macro instruction. In the 
GETMAIN macro instruction, the SP operand can be written to request 
storage from subpools 0 to 127; if this operand is omitted, subpool 0 is 
assumed. The operands that deal with subpools in the ATTACH macro 
instruction are: 

• GSPV and GSPL, whiqh give ownership of one or more subpools (other 
than subpool 6) to the task being created. 

• SHSPV and SHSPL, which share ownership of one or more subpools (oth- 
er than subpool 0) with the new subtask. 

• SZERO, which deternunes whether subpool 0 is shared with the 
subtask. 

All of these operands are optional. If they are omitted, no subpools 
are given to the subtask, and only subpool 0 is shared. 

Creating a Subpool : A new subpool is created whenever any of the 
operands described above is written in an ATTACH or a GETMAIN macro 
instruction, and that operand specifies a subpool which is not currently 
owned by or shared with the active task. If one of the ATTACH macro 
instruction operands causes the subpool to be created, the subpool numb- 
er is entered in the list of subpools owned by the task, but no blocks 
are assigned and no storage is actually allocated. If a GETMAIN macro 
instruction results in the creatioii of a subpool, the subpool number is 
assigned to one or more 4096-byte blocks, and the requested storage is 
allocated to the active task* In either case, ownership of the subpool 
belongs to the active task; if the sqbpool is created because of an 
ATTACH macro instruction, ownership is transferred or retained dependling 
on the operand used. 

Transferring Ownership : An owning task gives ownership of a subpool to 
a direct subtask by using the GSPV or GSPL operands in the ATTACH macro 
instruction issued when that subtask is created. Ownership of a subpool 
can be given to any subtask of any task, regardless of the control level 
of the two tasks involved and regardless of how ownership was obtained. 
A subpool cannot be shared with one or more subtasks and then trans- 
ferred to another subtask, however; an attempt to do this results in 
abnormal termination of the active task. Ownership of a subpool can 
only be transferred if the active task has ownership; if the active task 
is having a subpool and an attempt is made to pass ownership to a sub- 
task, the subtask receives shared control and the originating task 
relinquishes the subpool. Once ownership is transferred to a subtask or 
reliiiquished, any subsequent use of that subpool number by the originat- 
ing task results in th^ creation of a new subpool- When a task that has 
ownership of ojae or more subpools teriif^inates, all of the virtual storage 
areas in those subpools are released- Therefore, the task with owner- 
ship of a subpool should not terminate until all tasks or subtasks shar- 
ing the subpool have cc^apleted their use of the subpool. 

Sharing a Subpool ; Shared use of a subpool can be given to a direct 
subtask of any task with ownership or shared control of the subpool. 
Shared use is given by specifying the SHSPV and SHSPL operands in the 
ATTACH macro instruction issued when the subtask is created. Any task 
with ownership or shared control of the subpool can add to or reduce the 
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size of the subpool through the use of GETMAIN and FREEMAIN macro 
instructions. When a task that has shared control of the subpool ter 
minates, the subpool is not affected. 



Subpools in Task Communication ; The advantage of subpools in virtual 
storage management is that, by assigning separate subpools to separate 
subtasks, the breakdown of virtual storage into small fragments is 
reduced. An additional benefit from the use of subpools can be realized 
in task communication. A subpool can be created for an originating task 
and all parameters to be passed to the subtask placed in the subpool. 
When the subtask is created, the ownership of the subpool can be passed 
to the subtask. After all parameters have been acquired by the subtask, 
a FREEMAIN macro instruction can be issued, under control of the sub- 
task, to release the subpool virtual storage areas. In a similar mann- 
er, a second subpool can be created for the originating task, to be used 
as an answer area in the performance of the subtask. When the subtask 
is created, the subpool ownership would be shared with the subtask. 
Before the subtask is terminated, all parameters to be passed to the 
originating task are placed in the subpool area; when the subtask is 
terminated, the subpool is not released, and the originating task can 
acquire the parameters. After all pareuneters have been acquired for the 
originating task, a FREEMAIN macro instruction again makes the area 
available for reuse. 



I MPLICIT REQUESTS FOR VIRTUAL STORAGE 

You make an implicit request for virtual storage every time you issue 
a LINK, LOAD, ATTACH, or XCTL macro instruction. In addition, you make 
an implicit request for virtual storage when you issue an OPEN macro 
instruction for a data set. This section discusses some of the techni- 
ques you can use to cut down on the amount of real storage required by a 
job step, and the assistance given you by the control program. 



Reenterable Load Modules 

A reenterable load module is designed so that it does not modify 
itself during execution. Only one copy of the load module is paged into 
real storage to satisfy the requirements of any number of tasks in a job 
step. This means that even though there are several tasks in the job 
step and each task concurrently uses the load module, the only real 
storage needed is an area large enough to hold one copy of the load 
module (plus a few bytes for control blocks) . The same amount of real 
storage would be needed if the load module were serially reusable; 
however, the load module could not be used by more than one task at a 
time. 



Reenterable Macro Instructions 

All of the macro instructions described in this manual can be written 
in reenterable foriti- These macro instructions are classified as one of 
two types: macro instructions which pass parameters in registers 1 and 
0, and macro instructions which pass parameters in a list. The macro 
instructions that pass parameters in registers present no problem in a 
reenterable program; when the macro instmiction is coded, the required 
operand values should be contained in registers. For example, the POINT 
macro instruction requires that the DCB address and block address be 
coded as follows: 

[symbol] POINT deb address , block address 
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One method of coding this in a reenterable program would be to require 
that both of these addresses refer to a portion of storage allocated to 
the active task through the use of a GETMAIN macro instruction. The 
addresses would change for each use of the load module. Therefore, you 
would load one of the general registers 2-12 with the address, and 
designate the appropriate registers when you code the macro instruction- 
If register 4 contains the DCB address; and register 6 contains the block 
address, the POlliiT macro instruction is written as follows: 



POINT m , (6) 



The macro instructions that pass parameters in a list require the use 
of special forms of the macro instruction when used in a reenterable 
program. The macro instructions that pass parameters in a list are 
identified within their descriptions in the macro instruction section of 
this manual. The expansion of the standard form of these macro instruc- 
tions results in an in-line parameter list and executable instructions 
to branch around the list, to load the address of the list, and to pass 
control to the required control program routine. The expansions of the 
list and execute forms of the macro instruction simply divide the func- 
tions provided in the standard form expansion: the list form provides 
only the parameter list, and the execute form provides executable 
instructions to modify the list and pass control. You provide the 
instructions to load the address of the list into a register. 



The list and execute forms of a macro instruction are used in con- 
junction to provide the same services available from the standard form 
of the macro instruction. The advantages of using list and execute for- 
ms are as follows: 



• Any operands that remain constant in every use of the macro instruc- 
tion can be coded in the list form. These operands can then be 
omitted in each of the execute forms of the macro instruction which 
use the list. This can save appreciable coding time when you use a 
macro instruction many times. (Any exceptions to this rule are 
listed in the description of the execute form of the applicable 
macro instruction.) 



• The execute form of the macro instruction can modify any of the 
operands previously designated. (Again, there are exceptions to 
this rule. ) 

• The list used by the execute form of the macro instruction can be 
located in a portion of virtual storage assigned to the task through 
the use of the GETMAIN macro instruction. This ensures that the 
program remains reenterable. 

Figure 40 shows the use of the list and execute forms of a DEQ macro 
instruction in a reenterable program. The length of the list con- 
structed by the list form of the macro instruction is obtained by sub- 
tracting two sy^olic addresses; virtual storage is allocated and the 
list is moved into the allocated area. The execute form of the DEQ 
macro instruction does not modify any of the operands in the list form. 
The list had to be moved to allocated storage because the control pro- 
gram can store a return code in the list when RET=HAVE is coded. Note 
that the coding in the routine labeled MOVERTN is valid for lengths up 
to 255 bytes only. Some macro instructions do produce lists greatet* 
than 255 bytes when many operaaids are coded (for example , OPEN aind GLOSE 
with many data control blocks, or ENQ and DEQ with many resources) , so 
in actual practice a lengrth check should be made. 
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Figure 40. Using the list and the execute forms of the DEQ macro 
instruction in a reenterable program 



Nonreenterable Load Modules 

The use of reenterable load modules does not automatically conserve 
virtual storage; in many applications it will actually prove wasteful. 
If a load module is not used in many jobs and if it is not employed by 
more than one task in a job step, there is no reason to make the load 
module reenterable. The allocation of virtual storage for the purpose 
of moving coding from the load module to the allocated area is a waste 
of both time and virtual storage when only one task requires the use of 
the load module - 

You should not make a load module reenterable or serially reusable if 
reusability is not really important to the logic of your program. Of 
course, if reusability is important, you can issue a LOAD macro instruc- 
tion to load a reusable module, and later issue a DELETE macro instruc- 
tion to release its area. 

Freeing of Virtual Storage 

As indicated previously, the control program establishes two respon- 
sibility counts for every load module brought into virtual storage in 
response to your requests for that load module. The responsibility 
counts are lowered as follows : 

• If the load module was requested in a LOAD macro instruction, that 
responsibility count is lowered using a DELETE macro instruction. 

• If the load module was requested in a LINK, ATTACH, or XCTL macro 
instruction, that responsibility count is lowered using an XCTL 
macro instruction or Iqr returning control to the control program. 
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• When a task is terminated, the responsibility counts are lowered by 
the number of requests for the load module made in LINK, LOAD, 
ATTACH i and XCTL macro instructions during the performance of that 
task^ minus the number of deietibHs indicated ^bove; 

The virtual storage area occupied by a load modiile can be released by 
issuing a FREEMAIN macro instruction when the responsibility counts 
reach zero. When you pl^n your program, you can design the load modules 
to give you the best trade-off between execution time and efficient pag- 
ing. If you use a load module many times in the course of a job step, 
issue a LOAD macro instruction to bring it into virtual storage; do not 
issue a DilLETE macro instruction vtntil the load module is no longer 
needed. Conversely^ if a |:bad modiile is used only once during the job 
step» or if its uses are Widely sepafited* issue a link macro instruc- 
tion to obtain the Aiodiale and issidi^ an xctl from the module (or return 
control to the cdnttol pro<gfain) after It has been executed. 

There is a minor problem involved in the deletion of load modules 
containing data control blocks. An OPEN macro instruction must be 
issued before the data control block is used, and a close macro instruc- 
tion issued when it's ho longer needed. If you do not issue a CLOSE 
macro instruction for the Sata control blocks the control program issues 
one for you when the task is telrminatied. However^ if the load module 
containing the data cdlitroi block has been removed from virtual storage, 
the attempt to issue the CLOSE macro instruction causes abnormal ter- 
mination of the task. You must either issue the CLOSE macro instruction 
yourself before deleting the load module, or ensure that the data con- 
trol block is still in virtual storage when the task is terminated. 
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CHAPTER 8; MISCELLANEOUS SERVICES 



TIMI NG SERVICES 

Interval timing is a standard feature of VS. It provides the ability 
to request the date and time of day and provides for setting, testing, 
and canceling intervals of time. 



Date and Time of Day 

The operator is responsible for initially supplying the correct date 
and the time of day in terms of a 24 -hour clock. You request the date 
and time of day using the TIME macro instruction. The control program 
returns the date in register 1 and the time of day in register 0 or in a 
doubleword supplied by you if the MIC operand was specified. 



The date is returned in register 1 as packed decimal digits of the 
form OOyydddc, where yy are the last two digits of the year and ddd is 
the day of the year. C is the sign character hexadecimal F, which 
allows the year and day information to be unpacked directly for print- 
ing. One procedure used to request the date and time is shown in Figure 



The time of day is returned in register 0 in the form specified in 
the TIME macro instruction- The time of day is returned as an unsigned, 
32-bit, binary number that specifies the elapsed number of either hun- 
dredths of a second, if BIN is coded, or timer units, if TU is coded. 
(A timer unit is equal to 26.04166 microseconds.) If DEC is coded or 
the operand is omitted, the time of day is returned as packed decimal 
digits of the form HHMMSSth (hours, minutes, seconds, tenths of a 
second, and hundredths of a second). The packed decimal digits can be 
unpacked by changing the "h" value to a zone sign and using an UNPK 
instruction or by inserting zones between each decimal digit. If MIC 
was specified, the time of day is returned in the doubleword supplied, 
with bit 51 the low-order digit of the value. Register 0 is set to 0, 
and register 15 has the return code for MIC. 

All references to time of day and date use the time-of-day (TOD) 
clock, a 6U-bit binary counter. The TOD clock runs continuously while 
the power is on; the clock is not affected by the system stop- 
conditions. The operator normally sets the clock only after an inter- 
ruption of CPU power has caused the clock to stop, and restoration of 
power has restarted it. The operator sets the clock using the SET com- 
mand with the DATE and CLOCK parameters. (For more information about 
the TOD clock, see IBM Svstem/370 Principles of Operation .) 



41. 



TIME 
ST 
UNPK 
01 



1,ANS 

DOUBLE, ANS 
DOUBLE+7,X*F0* 



Request date and time 
Store packed date 
Unpack date for printing 



ANS 
DOUBLE 



DS 

DS 



F 

D 



Fullword for packed date 
Doubleword for unpacked date 



J 



Figure 41. Requesting the date and time 
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Interval Timing 



A time interval, up to a maximum of 24 hours, can be established for 
any task in the job step through the use of the STIMER macro instruc- 
tion, and the time remaining in the interval can be tested and canceled 
through the use of the TTIMER macro instruction- Each task in the job 
step can have an active time interval. The time interval can be estab- 
lished by any one of the following five methods. 

• BINTVL: Requires an unsigned 32-bit binary number, the low-order 
bit having a value of 0.01 seconds. 

• TUINTVL: Requires an unsigned 32-bit binary number, the low-order 
bit having a value of 26.04166 microseconds (1 timer unit). 

• DINTVL: Requires an 8-byte field containing unpacked decimal digits 
of the form HHliMSSth (hours, minutes, seconds, tenths and hundredths 
of a second, based on a 24-hour clock) . 

• TOD: Requires an 8-byte field similar to the field required for 
DINTVL. The control program interprets the time specified as the 
time of day at which the interval is to expire. 

• JMIC: Requires an 8-byte field containing an unsigned 64-bit binary 
number, bit position 51 of which is the low-order digit of the 
interval value. 

When you test the time remaining in the interval with the TU option 
(default) , the time remaining is returned as a 32-bit, unsigned, binary 
number in register 0, the low-order bit having a value of 26.04166 
microseconds. If you test the time remaining with TTIMER MIC, the time 
remaining is returned in microseconds in the specified area. If the 
interval has already expired, the content of register 0 is set to 0. 

When you request a time interval, you also specify the manner in 
which the interval is to be decreased, through the use of the TASK, 
R£AL» or WAIT parameter of the STIMER macro instruction. REAL and WAIT 
both indicate that the interval is to be decreased continuously, whether 
the associated task is active or not, TASK indicates that the interval 
is to be decreased only when the associated task is active. If REAL or 
TASK is coded, the task continues to compete with the other ready tasks 
for control; if WAIT is coded, the task is placed in the wait condition 
until the interval expires , at which time the task is placed in the 
ready condition. 

When TASK or REAL is designated, the address of a timer completion 
exit routine can be specified. This is the first routine to be given 
control when the associated task is made active after the completion of 
the time interval. (If the address of the exit routine is not speci- 
fied, there is no notification of the completion of the time interval.) 
The exit routine must be in virtual storage when required, and must save 
and restore registers and return control to the address in register 14. 
After control is returned to the control program, control is passed to 
the next instruction in the main program. 

Figure 42 shows the use of a time interval when testing a new loop in 
a program. The STIMER macro instruction sets a time interval of 5.12 
seconds, which is to be decreased only when the task is active, and pro- 
vides the address of a routine called FIXUP to be given control when the 
time interval expires. The loop is controlled by a BXLE instruction. 

The loop continues as long as the value in register 12 is less than 
or equal to the value in register 7. If the loop stops, the TTIMER 
macro instruction causes any time remaining in the interval to be can- 
celed; the exit routine is not given control. If, however, the loop 
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Figure 42. Interval timing 



is still in effect when the time interval expires, control is given to 
the exit routine FIXUP. The exit routine saves registers eind turns on 
the switch tested in the loop- The FIXUP routine could also print out a 
message indicating that the loop did not go to completion. Registers 
are restored and control is returned to the control program. The control 
program returns control to the main program and execution continues. 
When the switch is tested this time, the branch is taken out of the 
loop. Caution should be used to prevent a timer exit routine from issu- 
ing an STIMER specifying the Scunne exit routine. An infinite loop may 
occur. 

The priorities of other tasks in the system may also affect the 
accuracy of the time interval measurement. If you code REAL or WAIT, 
the interval is decreased continuously and may expire when the task is 
not active. (This is certain to happen when WAIT is coded.) After the 
time interval expires, assuming the task is not in the wait condition 
for any other reason, the task is placed in the ready condition and then 
competes for CPU time with the other tasks in the system that are also 
in the ready condition. The additional time required before the task 
becomes active will then depend on the relative dispatching priority of 
the task. 



EXTENDED- PRECISION FLOATING-POINT SIMULATION 

The System/370 Extended-Precision Floating-Point Simulator provides 
full extended- precision arithmetic for all OS users. A divide macro 
instruction (DXR) is provided for the models that have the extended- 
precision floating arithmetic facility and all eight instrixitions are 
provided for the models that do not. Thus, you can use extended- 
precision floating-point instructions whether or not your particular 
machine model has the extended-precision floating-point facility. To do 
so, write a program-interruption-handling exit routine. The exit rou- 
tine is required: 
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• If your machine model already has the extended-precision floating- 
point facili.ty, and you also wish to use the extended- precis ion 
floating- point divide (DXR) macro instruction. 

• If your roaoh^ne ino<|el clo^g not hdiV€^ the extended-precision floating- 
point in?triiCtions,, but you wish to use these instructions and the 
extendedlr-precision f loating-'point diyide instruction. 

To determine if the extended-precision floating-point feature is 
installed in your CPU, call the module lEA^PSIM, which returns ai pointer 
to the appropriate simulator. 

The f orwiat of the extended^ precis ion floating-point divide (PXR) 
instruction is described in the macro instructions section, and the for- 
mats of the other extended-precision floating-^ point instructions are 
described in Principles of Operation . 

Extended-Precision Division 

To perform extended^ precis ion division, use the DXR macro instruction: 

DXR regl,reg2 

where xegl contains the dividend, reg2 the divisor. 

The first operand (the dividend) is divided by the second operand 
(the divisor) and is replaced by the normalized quotient. No remainder 
is preserved. For a discussion of normalization, refer to the section 
"Floating-Point Arithmetic" in Principles of Operation . 

Division Process 

The quotient fraction has 28 hexadecimal digits and is developed such 
that it is the largest number for which the absolute value of the pro- 
duct of the quotient and the divisor fractions is either equal to or 
less than the absolute value of the adjusted (normalized) dividend frac- 
tion. All digits of the dividend and divisor fractions are involved in 
the operation; the dividend fraction is extended with low- order zeros. 

The sign of the quotient is determined by the rules of algebra; 
however, if the quotient is made a true 0, its sign is made plus. 

Unless the quotient is made a true 0, the characteristic, sign, and 
high-order IH hexadecimal digits of the normalized quotient fraction 
replace the high-border part of the f i^st operand. The low-order 14 
hexadecimal digits of the quotient fraction replace the high-order part 
of the first operand. The low-order 14 hexadecimal digits of the quo- 
tient fraction replace the low-order fraction of the first operand. The 
low-order sign is made equal to the high-order sign, and the low-order 
characteristic is made 14 less than the high-order characterictic. 
However, when the subtraction of 14 causes the low-order characteristic 
to become less than 0, it is made 128 greater than its correct value. 
Extended-precision arithmetic is further discussed in Principles of 
Operation . 

Arithmetic Exceptions 

The following excerptions can occur when using the DXR macro 
instruction. 

• Exponent ov^i:flovj[» 

• E^qponent undeit^tiovi;*: 

• Floating-point divide. 
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Exponent overflow is recognized when the characteristic of the norma- 
lized quotient exceeds 127 and the fraction of the quotient is not 0. 
The operation is completed by making the high-order characteristic 128 
less than the current value. If the low-order characteristic also 
exceeds 127, it is decreased by 128. The quotient fraction and sign 
remain unchanged. A program interruption for exponent overflow then 
occurs. 



Exponent underflow is recognized when the characteristic of the nor- 
malized quotient is less then 0 and neither operand fraction is 0. If 
the exponent underflow mask bit is set, the operation is completed by 
making the characteristics of both parts 128 greater than their correct 
values. The quotient fraction and sign remain unchanged. A prograia 
interruption for exponent underflow then occurs. If the exponent unde- 
rflow mask is 0, a program interruption does not occur; instead, the 
operation is completed by making both the high-order and low- order parts 
of the quotient a true 0. 



Exponent underflow is not recognized when the low-order characterist- 
ic is less than 0 and the high-order characteristic is greater than or 
equal to 0. Similarly, exponent underflow is not recognized when one or 
both of the operands underflow during prenormalization, but the quotient 
can be expressed without encountering underflow. 

The floating-point divide exception is recognized when the divisor 
fraction is 0. The operation is suppressed, and a program interruption 
for floating-point divide occurs. 

When the dividend fraction is 0, the quotient is made a true 0, and a 
possible exponent overflow or underflow is not recorgnized. A division 
of 0 by 0, however, causes the operation to be suppressed and an inter- 
ruption for floating-point divide to occur. 

The condition code remains unchanged for all arithmetic exceptions. 
Figure 43 describes the program interruptions that can occur. 



Interruption 

Type 



Description 



Action 
Taken 



Operation 
Specification 



Exponent 
Overflow 



Exponent 
Underflow 



Floating- 
Point 
Divide 



The instruction is not installed. 



Registers other than 0 or U are 
specified, or positions 16-23 do not con- 
tain O's. 

The characteristic of the normalized 
quotient exceeds 127, and neither operand 
fraction is 0. 

The characteristic of the normalized 
quotient is less than 0, neither 
operand fraction is 0, and the exponent 
underflow mask bit is set. 

The divisor fraction is 0. 



The operation 
is suppressed. 

The operation 
is suppressed. 



The operation 
is completed. 



The operation 
is completed. 



The operation 
is suppressed. 



.x_. 



Figure 43. Summary of program interruptions 
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Calling the Simulator 



To use the extended-precision floating-point instructions ^^hat your 
machine model does not have,, call the extended-preGision floating-point 
simulator from a program-interruption-handling exit routine. The simu- 
lator is a program that is automatically included in your operating sys- 
tem at system generation time. Writing an exit routine to handle pro- 
gram interruptions is discussed under "Program Interruption Processing." 

To use the extended-precision f loating-^point simulator, specify in 
the SPIE macro instruction that your exit routine is to receive control 
if an operation exception occurs. In addition, the exit routine must 
perform the following tasksV in this order: 

• Check that the exception is for floating-point divide. 

• Prepare a parameter list to pass to lEAXPSIM. 

• Pass the control to lEAXPSIM, using standard operating system 
conventions. 

• Prepare a parameter list to pass to the simulator. 

• Pass control to the simulator, using standard operating system 
conventions . 

• Check the code returned by the simulator. 

• Perform corrective action if necessary. 

In addition, the exit routine may perform the following tasks: 

• Load the lEAXPSIM module, using the LOAD macro instruction, before 
its use. 

• Delete the lEAXPSIM module, using the DELETE macro instruction, aft- 
er its use- 

• Load the simulator, using the IX)AD macro instruction, the first time 
it is needed. 

• Delete the simulator, using the DELETE macro instruction, at the end 
of the job step. 

Designing the Exit Routine 

The following paragraphs and Figure 44 should help you design your 
exit routine . 

The parameter list that you pass to lEAXPSIM must be pointed to by 
register 1 and must contain a pointer to a doublewOrd area into which 
lEAXPSIM will move the name of the simulator module to which you will 
pass control. 

The parameter list that you pass to the simulator must be pointed to 
by register 1 and must contain the following: 

1. A pointer to the PIE. 

2. A pointer to the area containing the contents of general registers 
0 through 15 at interrupt time. 

3- A pointer to a work area, 

4. A pointer to a byte that is nonzero if the last bit of the quotient 
for a DXR need not be correct. 
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EXT PRE 



TOSIM 



USING 


EXTPRE,15 




STM 


3,13,SIMSV+12 


Save registers not in PIE 


LR 


U,15 




USING 


EXTPRE, U 


Establish addressability 


MVC 


SIMSV(12) ,20(1) 


Registers 0-2 from PIE 


MVG 


SIMSV+56(8),12(1) 


Registers 14-15 from PIE 


ST 


14, RET 


Save return addreiss 


ST 


1,PARMB 


Pointer to PIE 


LA 


13,SAVESIM 


Load save area address 


L 


15,SIMADD 




LTR 


15,15 


Does SIMADD contain 






address ? 


BNZ 


TOSIM 


If so, go directly to 






simulator 


LOAD 


EI'=IEAXPSIM 




LR 


15, 0 


Put IEAXPSIM»S address in 






register 


LA 


1, PARMA 


Load pointer to doubleword 


BALR 


14,15 


Get simulator's address 


DELETE 


EP=IEAXPSIM 




LOAD 


EPLOC=SIMUL 


Load simulator 


LR 


15,0 


Put simulator's address in| 






register | 


ST 


0,SIMADD 


Save address of simulator | 


LA 


1 , PARMB 


Parameter list address j 


BALR 


14,15 


Go to simulator | 


LTR 


15,15 


Error or exceptional ] 


BZ 


GOODOUT 


condition? | 



*HERE THE EXIT ROUTINE SHOULD DETERMINE THE ERROR OR THE 
♦EXCEPTIONAL CONDITION THAT OCCURRED IN SIMULATING AND 
♦TAKE APPROPRIATE ACTION. 



GOODOUT 



B 

EQU 



OUT 
* 



♦HERE THE EXIT ROUTINE SHOULD TAKE APPROPRIATE ACTION WHEN 
♦NO ERROR OR EXCEPTIONAL CONDITION OCCURRED DURING SIMULATION, 



OUT 



L 

LM 

BR 



14, RET 

3,13,SIMSV+12 
14 



Restore registers 
Return 



♦WHEN THE EXIT ROUTINE NO LONGER NEEDS THE SIMULATOR, 
♦THE ROUTINE SHOULD DELETE IT. 





DELETE 


EPLOC=SIMUL 




PARMA 


DS 


X'80' ,AL3 (SIMUL) 


Pointer to simulator name 


SIMUL 


DS 


D 


Simulator name 


PARMB 


DS 


F 


For pointer to PIE 




DC 


A (SIMSV) 


Address of register area 




DC 


A (WORK) 


Address of worjc area 




DC 


X*80* ,A13(ZER0) 


Divide adjust switch 








pointer 


ZERO 


DC 


X'C 


Adjust switch for divide 


WORK 


DC 


50D 


Work area 


SIMSV 


DS 


16F 


Register area 


SIMADD 


DC 


F'0» 


Address of simulatof 


RET 


DS 


F 


Return address 


SAVES IM 


DS 


18F 


Save area 


Figure 44. 


Calling 


the extended-precision floating-point simulator 
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The work area must be at least 30 doublewords (2U0 bytes) if your 
installation's machine model has the extended-precision floating-point 
facility or at least 50 doublewords (400 bytes) if it does n(bt. The 
exit routine shown in Figure 44 can be used for either type machine 
model because its work area is 50 doublewords. 

To ol)tain the name of the extended-precision floating-point simulator 
installed in your system, call the module lEAXPSIM, which returns a 
pointer to the name of the simulator in the doubleword that you provide. 
In Figure U4, the doubleword is SIMUL. 

Before passing control to the simulator, you can use the LOAD macro 
instruction to bring the simulator into virtual storage if it is not 
already there. The entry point ncune is specified as the name returned 
from lEAXPSIM. After issuing LOAD, you can pass control to the simula- 
tor, using standard calling conventions. 

Upon regaining control from the simulator, the exit routine should 
check register 15 for one of the two return codes shown in Figure 45. 

If the return code is X'FF', the exit routine determines the kind of 
error encountered by the simulator by examining the interruption code. 
Figure 46 shows the possible settings of the interruption code. 

The simulator adjusts the condition code in the old PSW in the PIE 
(bits 34-35) to indicate the result of an AXR or SXR macro instruction- 
When a program interruption occurs within the simulator while fetching 
the argument of the MXD macro instruction, the instruction address in 
the PSW in the PIE is restored to its setting at operation-interruption 
time. 

The simulator never alters the program check old PSW at location 40. 
Its interruption code will be an operation exception except for the MXD 
macro instruction, when it may be a protection, addressing, or specifi- 
cation exception. 

The simulator should be deleted by the using program if it was 
obtained by the LOAD macro instruction. 

If the full simulator (lEAXPALL) is loaded on a CPU that already has 
the extended-precision floating-point facility, no abnormal conditions 
result. Only the DXR macro instruction is simulated. However, the 
simulation of the DXR function is slower than if the lEAXPDXR were used, 
since the other extended-precision operations in the divide algorithm 
are also simulated. 

If lEAXPDXR is loaded on a CPU without the extended-precision 
floating-point facility, a OCl ABEND occurs when ah extended-precision 
divide is simulated. In the simulation of the other extended-precision 
macro instructions, a return code of X^FF' is passed to the caller and 
no simulation is attempted. 



r — • ■ ■ ■ — " — • • ■ — ■ : — -1 

I Hexadecimal | 
I Code Meaning j 
|..__ 

I GO The operation was successful. { 

I ■ I 

j FF The operation was not successful, or an exceptional | 

1 condition occurred. j 

: L^, - . . , : . . : ; — J 



Figure 45. Return codes from the extended-precision floating-point 
simulator 
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Meaning of Interruption 



The simulator found that the operation was not an 
extended-precision floating-point operation and 
returned control without further processing. 

Protection exception ^ ^ . 

Addressing exception^ ^ 

Specification exception^ ^ ^ 

Exponent overflow exception** 

Exponent underflow exception** 

Significance exception** 

Floating-point divide** 



0001 

0100 
0101 
0110 
1100 
1101 
1110 
1111 



^When the simulator encounters these exceptions, it stop processing 
and returns control to the exit routine. 

^An incorrect extended-precision floating-point register was speci- 
fied, the third byte of the DXR macro instruction was not X'OO*, or 
a register other than 0 or 4 was specified in the Rl or R2 field of 
the CXR macro instruction. 

3The error occurred during the processing of ah MXD macro 
instruction. 

'♦The error occurred during simulation. 

Figure US. Interruption codes returned by the simulator 



COMMUNICATING WITH THE SYSTEM OPERATOR 



The WTO and the WTOR macro instructions allow you to write messages 
to the operator. The WTOR macro instruction also allows you to request 
a reply from the operator. If your system has the MCS (multiple console 
support) option, messages can be sent to (and replies received from) as 

many as 32 operator consoles. 

There are two basic forms of the WTO macro instruction: the single- 
line form, and the multiple-line form. To use the single-line form, 
code the single-line message within apostrophes. The message that the 
operator receives does not contain these apostrophes. The message can 
include any character that is valid in a character (C-type) DC instruc- 
tion, except the new- line control character (hexadecimal value 15) . It 
is assembled as a variable-length record, which is written automatical- 
ly; you do not have to provide a data control block. 

To use the multiple-line form of the macro instruction, code the text 
of each line within apostrophes followed by a line type indicator- Enc- 
lose both of these items in one set of parentheses. Up to ten conti- 
guous lines of information may be passed to the operator's console. 

The following should be considered when issuing multiple-line WTO 
messages. 

• Multiple-line WTO messages are not passed to the user-written WTO 
exit routine. 

• When a console switch takes place, unended multiple-line WTC mes- 
sages and multiple-line WTO messages in the process of being written 
to the original console are not moved to the new console. 
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• When the system hard-copy log is an active operator's console, only 
the hard-copy versions of multiple-line messages are v/ritten to the 
console. 

• An active operator's console should be used a-s the hard-copy log 
only in an emergency- 
See the macro instructions section for an explanation of the parame- 
ters in the multiple- line form of the WTC macro instruction. 

The message is routed (in a system with the MCS option) using the 
routing codes speicif led in the WTO macro instruction. At systein genera- 
tion, each operator's console in the system is assigned routing codes 
which correspond to the functions that the installation wants that con- 
sole to perform. When any of the routing codes assigned to a message 
match any of the routing codes assigned to a console, the message is 
sent to that console. For more information about routing codes, refer 
to Appendix C. (For RES users, the message is routed according to the 
user's queue identification number (QIE).) 

Disposition of the message (in a system with the MCS option) is indi- 
cated through the descriptor codes specified in the WTC macro instruc- 
tion. Descriptor codes classify WTO messages so that they may be prop- 
erly presented on, and deleted from, display devices. Each WTO macro 
instruction should contain one descriptor code. The descriptor code is 
not printed or displayed as part of the message text. If a descriptor 
code of 1 or 2 is coded into the WTO macro instruction, an indicator (♦ 
or a) is inserted as the first character of the message. The indicator 
informs the operator that he is required to take some immediate action. 
If a descriptor code other than 1 or 2 is coded, a blank is inserted as 
the first character, indicating that no immediate action is needed- For 
more information about descriptor codes, refer to Appendix C. 

A sample WTO macro instruction is shown in Figure 47. The routing 
code (ROUTCDE) and descriptor code (DESC) keyword parameters are ignored 
if the MCS option is not included in the system (except for WTP; see 
Writing to the Programmer below) . 

To use the WTOR macro instruction, you code the message exactly as 
designated in the single-line WTO macro instruction. (The WTOR macro 
instruction cannot be used to pass multiple-line messages.) When the 
message is written, the control program adds a two-character message 
identifier before the message to associate the reply with the message. 
The control program also inserts an indicator as the first character of 
all WTOR messages, thereby informing the operator that immediate action 
is required. You must, however, indicate the response desired. In 
addition, you must supply the address of the area in which the control 
program is to place the reply, and you must indicate the length of the 
reply. The length of the reply may not be zero. You also supply the 
address of an event control block which the control program posts after 
the reply has been placed, left-ad justed, in your designated area. 
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single-line WTO 
format 

Multiple- WTO 
line format 
(list form) 



•BREAKOFF POINT REACHED. TRACKING COMPLETED.', C j 

R0UTCDE=14, DESC=7 | 

('SUBROUTINES CALLED', C), C | 

('ROUTINE TIMES CALLED' ,L) ,( 'SUBQUER' ,D) , C | 

( 'ENQUER' ,D) , ('WRITER' ,D) , C j 

CDQUER' ,DE) , C j 

ROUTCDE=(2,14),DESC=(7,8),MF=L | 



Figure U7. Writing to the operator 



XC ECBAD,ECBAD Clear ECB 

WTOR 'STANDARD OPERATING CONDITIONS? REPLY YES OR NO', 

REPLY , 3 , ECBAD , ROUTCDE= (1,15), DESC=7 
WAIT ECB= ECBAD 



ECBAD 
REPLY 



DC 
DC 



F'O' 
C'bbb' 



Event control block 
Answer area 



Figure 48. Writing to the operator with a reply 



A sample WTOR macro instruction is shown in Figure 48. The reply is 
not necessarily available at the address you specified until a WAIT 
macro instruction has teen issued. 

When a WTOR macro instruction is issued with more than one routing 
code, any console within those areas has the authority to reply. The 
first reply received by the control program is returned to the issuer of 
the WTOR, providing the syntax of the reply is correct. If the syntax 
of the reply is not correct, another reply is accepted- The WTOR is 
satisfied when the control program moves the reply into the issuer's 
reply area and posts the event control block. Each console that 
received the original WTOR will also receive the accepted reply. The 
master console operator may answer any WTOR, even if he did not receive 
the original message. 



WRITING TO THE PROGRAMMER 

The WTO and the WTOR macro instructions allow you to write messages 
to the programmer, as well as to the operator. At system generation, 
your installation determines how many 176-fcyte SMBs (system message 
blocks) to allow. You can override this number at initial program load; 
however, the number of SMBs allowed must range from 1 to 20. 

When you submit your job, you can specify the message output class 
for your messages by using the MSGCLASS parameter of the JOB statement. 
(For a description of the MSGCLASS parameter, refer to the Job Control 
Language Reference manual.) All WTO and WTOR messages within the number 
of SMBs allowed per job will appear in the designated message output 
class. When you exceed the number of allowable SMBs, no subsequent mes- 
sages will appear in the message output class . 

To write a message to the programmer, you must specify R0UTCDE=11 in 
the WTO or the WTOR macro instruction. If you use routing code 11 alone 
or together with other routing codes, the message goes to the message 
output class, as described above. The message can also go to the 
console(s> in the situations described by Figure 49. 
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j If you specify a routing code of 11 (R0UTCDE=11) 
|.«_.. ^ ^ 

I In this macro instruction: | In a system: | Your message goefe to the:| 
- 



WTO 



With MCS I Message output class; 

I Consoles designated to 

I receive message with 

I ROUTCDE=ll 



WTO 



Without NCS I Message output class 



WTOR 



With MCS j Message output class; 

I Master console 



WTOR 



Without MCS 



j Message output class; 
I Master Console 

-JL . ■ 



If, in addition to routing code 11, you specify the appropriate 
routing code(s) in either a WTO or a WTOR macro instruction with or 
without MCS, the message appears on the consoleCs) designated to 
receive the routing code(s). In addition, the message appears in 
the same places as it does when you specify only routing code 11 Cas 
shown above), with one exception. For WTOR with MCS, the message 
goes to the roaster console only if you specify that console's rout- 
ing code. 

Figure 49. Using WTO and WTOR to write messages to the programmer 



WRITING TO THE HARD-COPY LOG 

When using an operating system that has the MCS (multiple console 
support) option, you can record information on the hard- copy log. Since 
the MCS option allows more than one console in a system, an installation 
might find it helpful to be able to record all the messages issued by 
and to a system. The hard-copy log provides a place to collect these 
messages and therefore allows an installation to review system activity 
by reviewing message activity. 

Since the hard-copy log is optional, you should know whether your 
system was generated with it. The hard-copy log is either an operator's 
console with output capability or the system log. 

To record information on the hard-copy log, you use the WTO or WTOR 
macro instruction. Your installation must have decided which system 
fxinctions are to be logged and assigned appropriate routing codes to the 
hard-copy log. The routing codes that you assign to your WTO or WTOR 
macro instruction are compared to the routing codes assigned to the log. 
If one or more codes match, the message is entered in the log. This 
means you do not have to issue a WTL macro instruction to record system 
and problem program information when the same information is going to 
the operator. You must, however, know which system functions the log is 
recording and assign an appropriate routing code to your WTO or WTOR 
macro instruction. 

For each entry in the hard-copy log, both the time when the message 
is received by the system and the routing codes for the message are 
appended to the beginning of the message text- Recording the time that 
the message was received, a procedure called time stamping, allows you. 
to obtain a chronological record of system activity. For a system that 
does not have the timer option, the space for time stamping is filled 
with zeros. 

Whether the hard-copy log is the operator's console or the system 
log, the hard-copy log information cannot te confused with other infor- 
mation. This is because the hard-copy log entries are prefixed with the 
time stamp and the routing codes. 
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WRITING TO THE SYSTEM LOG 



The system log (optional in VSl, standard in VS2) consists of two 
SYSOUT data sets on which the communication between the operator and the 
system is recorded. You can use the system log by coding the informa- 
tion that you wish to log in the "text" operand of the WTL macro 
instruction. 

The data set receiving data from the control program, user programs, 
and operators is the primary data set. The data set being written, or 
waiting to be written, to a system output device is the alternate data 
set. The primary data set, the one that is open and receiving input, is 
logically connected to two buffers. The control program fills one buff- 
er and writes it to the primary data set while filling the other buffer. 
The alternate data set has been logically disconnected from the buffers 
because it has been filled and must wait to be written to a system out- 
put device. After being written to a system output device, the altern- 
ate data set can be used again to receive input. When receiving input, 
the alternate data set becomes the primary data set. 

When the WTL macro instruction is executed, the control program 
places your text in one of the buffers and, when the buffer is full, 

writes the buffer onto the system log primary data set. The control 
program writes the text of your WTL macro instruction on the master con- 
sole instead of on the system log if one of the following two conditions 

exists: 

• The system log is not supported. 

• The system log is supported, but the system log data sets are tem- 
porarily inactive because both are full and waiting to be written. 

Your installation probably has an operator procedure to follow for both 
of the above conditions. 

Although when using the WTL macro instruction you code the message 
within apostrophes, the written message does not contain the apos- 
trophes. The message can include any character that is valid for the 
WTO macro instruction and is assembled and written the same way as the 
WTO macro instruction. MCS routing codes and descriptor codes are not 
assigned, since they are not needed by the WTL macro instruction. 



MESSAGE DELETION 

If your system is using a cathode-ray tube (CRT) display as a con- 
sole, unnecessary messages can be deleted from the operator's screen by 
the programmer- The control program assigns a message identification 
number to each WTO and WTOR message and returns the message identifica- 
tion number in register 1. The DOM macro instruction uses the identifi- 
cation number to indicate which message is to be deleted. The message 
identification number must not be confused with the reply identification 
number that is assigned to WTOR replies. 



GENERALIZED TRACE FACILITY INTERFACE 

One of the capabilities of GTF (generalized trace facility) is the 
recording of data originated by application programs. The interface 
between the application programs and GTF is the GTRACE macro instruc- 
tion. (For a complete discussion of GTF, see the Service Aids 
publication.) 

GTRACE allows from 1 to 256 bytes of data to be entered in a GTF 
buffer and recorded. When the GTRACE macro instruction is executed, GTF 
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mus^ be active and conditioned to receive application data and to record 
this data on an external device; otherwise the data will not be 
accepted. Return codes are used to indicate the result of the 
operation. 

Recorded data is processed by the edit function of the HMDPRDMP ser- 
vice aid* If you want more than a hexadecimal dump of the records, you 
may prepare formatting routines for use with the HjMDPFDMP edit function. 
Association between your recorded data and the formatting routine that 
is to process it is established by entering a format identifier in the 
GTRACE macro instruction. This identifier defines the formatting rou- 
tine that is to process the record. For a more complete discussion of 
HMDPRDMP, see the Service Aids publication. 

To use the GTRACE macro instruction, specify the address and the 
number Of bytes of data to be entered, along with an event identifier. 
A unique event identifier may be specified each time the GTRACE macro 
instruction is used. This identifier may be used, for example, in out- 
put record identification- The optional FID parameter indicates the 
formatting routine to be used by HMDPRDMP in processing the record. In 
Figure 50, 200 bytes of data, beginning at location AREA, are to be 
recorded with an event identifier of 37. In Figure 50 HMDUSR28 is 
designated. 



J. . ^ 

j GTRACE DATA=AREA,LNG=200,ID=37,FID='»0 | 

L . . . ^ . J 

Figure 50. Using the GTRACE macro instruction 
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PART II; MACRO INSTRUCTIONS 



CHAPTER 9: INTRODUCTION TO SUPERVISOR MACRO INSTRUCTIONS 



You can communicate service requests to the control program using a 
set of macro instructions provided by IBM. These macro instructions are 
available only when programming in the assembler language, and are pro- 
cessed by the assembler program using macro definitions supplied by IBM 
and placed in the macro library when the system was generated. 

The processing of the macro instruction by the assembler program 
results in a macro expansion, generally consisting of data and execut- 
able instructions in the form of assembler language statements. The 
data fields are the parameters to be passed to the requested control 
program routine; the executable instructions generally consist of a 
branch around the data, instructions to load registers, and either a 
branch instruction or a supervisor call (SVC) to give control to the 
proper program. The exact macro expansion appears as part of the 
assembler output listing. 



MACRO INSTRUCTION FORMS 

When written in the standard form, some of the macro instructions 
result in instructions that store into an inline parameter list. The 
option of storing into an out-of-line parameter list is provided to 
allow the use of these macro instructions in a reenterable program. You 
can request this option through the use of list and execute forms. When 
list and execute forms exist for a macro instruction, their descriptions 
follow the description of the standard form. 

Use the list form of the macro instruction to provide a parameter 
list to be passed either to the control program or to a problem program, 
depending on the macro instruction. The expansion of the list form con- 
tains no executable instructions; therefore registers cannot be used in 
the list form. 

Use the execute form of the macro instruction in conjunction with one 
or two parameter lists established using the list form. The expansion 
of the execute form provides the executable instructions required to 
modify the parameter lists and to pass control to the required program. 
Only the ATTACH, LINK, and XCTL macro instructions use two parameter 
lists: a problem program list, resulting from the address parameter and 
VL operands, and a control program list, resulting from the remaining 
operands. The control program list is required, and the problem program 
list is optional in these macro instructions. 

The CALL, DEQ, ENQ, and SNAP macro instructions can result in vari- 
able length parameter lists. The length of the parameter list generated 
by the list form of the macro instruction roust be equal to the maximum 
length list required by any execute form that refers to the list. The 
maximum length list can be constructed in one of three methods: 

• Code the parameters required for the maximum length execute form in 
the list form. 

• Provide a DS instruction immediately following the list form to 
allow far the maximum length parameter list. 
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•Acquire a maximuin length list by using commas in the list form to 
indicate the maximum number of parameters. For example, the STORAGE 
operand of the SNAP macro instruction could be coded as STORAGE= 
(rrrvrfvr) "to allow for five pairs of addresses. The actual 
addresses would be provided in the execute form. 



CODING AIDS 

The symbols [ ], { }, and are used to indicate how a macro 

instruction may be written. DO NOT CODE THESE SYMBOLS. The specific 
meanings of these symbols are given at the bottom of each page on which 
they are used; their general definitions are given below: 

( ] indicates optional opercinds. The operand enclosed in the brackets 
(for example, [VL]) may or may not be coded, depending on whether 
or not the associated option is desired. If more than one item is 
enclosed in brackets (for example, fREREADl ), one or none of the 
items may be coded. LlEAVE J 

£ > indicates that a choice must be made. One of the operands from the 
vertical stack within braces (for example, rpLnput 1)) must be 

(LoutputJ/ 

coded, depending on which of the associated services is desired. 

indicates that more than one set of operands may be designated in 
the same macro instruction. 

indicates a value that is used in default of a specified value. 

This value is assumed if the operand is not coded. 



WRITING THE MACRO INSTRDCTIONS 

The system macro instructions are written in the assembler language, 
and are subject to the rules contained in the publication VS Assembler 
Language . Write system macro instructions, like all assembler language 
instructions, in the following format: 

r • T T ■ — : ■ ^ ■ — T- ■ 1 

I Name | Operation | Operands j Comments | 
^ 1 ^ 

I symbol | Macro name | Blank, or one or more operands | | 

I or I I separated by commas j I 

I blank I I I I 

L . . X . X . . . X——, — . — J 

Use the operands to specify the services and options to be performed; 
write them according to the following general rules: 

• If the selected operand is written in all capital letters (for 
example, STEP, DUMP, RET=USE), code the operand exactly as shown. 

• If the selected operand is Written in lower case letters, substitute 
the indicated value, address, or name. 

• If the selected operand is a combination of capital and lower case 
letters separated by an equal sign (for example, EP=entry point 
name), code the capital letters and equal sign as shown, then make 
the indicated substitution. 

• Code commas and parentheses exactly as shown, only omit the comma 
following the last operand coded. The use of commas and parentheses 
is indicated by brackets and braces, exactly as operands. 
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When substitution is required, the method of specifying the operand 
depends on the requirements of the control program. Descriptions of 
list and execute form macro instructions indicate specifically how the 
operands should be coded; the descriptions of the standard forms of the 
macro instructions indicate only what is to be coded. Appendix A shows 
specifically how the operands are to be coded. The table in Appendix A 
contains all of the operands for which substitution is required and 
indicates the allowable ways of writing the operands. The classifica- 
tions are as follows: 



SYM 

is any symbol valid in the assembler language. 



DEC DIG 

is any decimal digit up to the value indicated in the associated 
macro instruction description. If both SYM and DEC DIG ar^ 
checked, an absolute expression is also allowed. 



REGISTER 

is always coded within parentheses, as follows; 

(2-12) - one of general registers 2 through 12 that you have pre- 
viously loaded with the right-adjusted value or address 
specified in the associated macro instruction description. 
The unused high-order bits must be set to zero. You may 
designate the register symbolically or with an absolute 
expression. 

(1) - general register 1, previously loaded as indicated above. 

Designate the register as (1) only. 
(0) - general register 0, previously loaded as indicated above. 

Designate the register as (0) only. 



RX TYPE 

is any address that is valid in an RX-type instruction (for 
example, LA) . 



ADCON TYPE 

is any address that may be written in an A-type address constant. 



CONTINUATION LINES 

You can continue the operand field of a macro instruction on one or 
more additional lines according to the following rules: 

1. Enter a continuation character (not blank, and not part of the 
operand coding) in column 72 of the line. 

2. Continue the operand field on the next line, starting in column 16. 
All columns to the left of column 16 must be blank. 

You can code the operand field being continued in one of two ways. 
Code the operand field through column 71, with no blanks, and continue 
in column 16 of the next line; or truncate the operand field by a comma, 
where a comma normally falls, with at least one blank before column 71, 
and then continue in column 16 of the next line. Figure 51 shows an 
example of each method. Additional information on the continuation of 
any assembler language macro instruction is provided in the publication 
VS Assembler Lanqauge . 
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ADDITIONAL BIAGRO INSTRUCTIONS 



Descriptions and definitions of the following macro instructions are 
contained in the publications VSl Planning and 0s e Guide and VS2 Plam-- 
ning and Use Guide . 

ATLAS PURGE 

CATALOG RESERVE 

CIRB RESTORE 

CVT SMFWTM 

EOV STAE 

EXTRACT SYNCH 
MODESET * TESTAUTH 



r- — • — ■ r -'"^ T— — — — — — - — • — — T-T 1 

I Name | Operation | Operand cominents | | | 

I NAMEl I OPl I OPERANDI, OPERAND2, OPERANDS, OPERANDS, OPERa|x| | 

1 I |VnD5, 'OPERANDS THIS IS ONE WAY j | j 

I NAME2 I 0P2 ^^ "l OPERANDI, OPERAND2, THIS IS |x| { 
I 1 I OPERANDS, ANOTHER WAY |X| | 
I I j 0PERAND4 I i I 
L X, . .-JL-. . X-X J 

Figure 51. Continuation coding 
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CHAPTER 10; DESCRIPTIONS OF THE MACRO INSTRUCTIONS 



The macro instruct-ions are described in alphabetical order. For your 
convenience, the upper right-hand corner of each page contains the name 
of the macro instruction described on the page. 
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ABEND 



ABja^D— • Abnorroally Terminate a Task 

Use the ABEND macro instruction to abnormally terminate the active 
task and all its subtasks. ABEND can request a dump of all virtual 
storage areas and control blocks pertaining to the tasks being abnormal- 
ly terminated, and can specify that the entire job step is to be ahnorin- 
ally terminated. If the job step task is abnormally terminated or if 
ABEND specifies job step termination, the completion code is recorded on 
the system output device, and the remaining job steps in the job are 
either skipped or executed as specified in their job control statements. 

If the job step is not to be terminated, the following action is 
taken: 

• The task that was active vrtien ABEND was issued is terminated, along 
with all of the subtasks of that active task. 

• The completion code is posted as indicated in the completion code 
operand description. 

• One end-of-task exit routine is selected to be given control; the 
one specified in the ATTACH macro instruction that created the task 
that was active when ABEND was issued. The exit routine is given 
control when the originating task of the task for which ABEND was 
issued beccnnes active. None of the end-of-task exit routines speci- 
fied for any subtasks of the task for which ABEND was issued are 
given control. 

The ABEND macro instruction is written as follows: 

r T T 1 

I [symbol] | ABEND | completion code C , DUMP] (, STEP! 1 

L. X X . . . ;_«^_J 

completion code 

is a maximum of U095. The value may be specified symbolically, as 
a decimal digit, or as one of the registers 1 through 12 (in paren- 
theses). Using a value greater than 4095 causes unpredictable user 
or system completion codes, or both. If the job step is to be ter- 
minated, the completion code is recorded as user code on the system 
output device. If the job step is not to be terminated, the com- 
pletion code is placed in the task control block of the active task 
and in the event control block specified in the ECB operand of the 
ATTACH macro issued to create the active task. 

DUMP 

is written as shown. It is used t;o request a dump of all virtual 
storage areas assigned to the task and all control blocks pertain- 
ing to the task. A scuoaple abnormal termination dump is contained 
in the VSl and VS2 Debugging Guides . 

A separate dump is provided for each of the tasks being terminated 
as a result of ABEND. In addition, a dump of the control blocks 
euad save areas is provided for each of the higher level tasks that 
are direct predecessors of the task being terminated. You should 
provide a //SYSABEND or a //SYSUDUMP DD statement; if you do not, 
you receive only an indicative dump. If the operand is omitted or 
if insufficient storage is available in the partition for the 
abnoxmal temdnation to be performed, no dump is provided. 



C ] indicates optional name or operands . 
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ABEND 



STEP 

is written as shown. It indicates that the entire job step of the 
active task is to be abnormally terminated. 

Note : During the ABEND process, the terminating task is multiprogrammed 
with other tasks in the system. Therefore, the resulting storage dump 
may reflect changes that occur during ABEND execution to storage areas 
not uniquely related to the abnormally terminating task. 
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ATTACH — Create a New Task (VSl) 

Use the ATTACH macro instruction to create a new task. The new task 
is a subtask of the oric|inatinq task.^ Both tasks exist in the same par- 
tition and compete for execution with each other and with all other 
tasks in the system, basied on dispatching priority. The limit and dis~ 
patching priorities of the new subtask are the same as those of the ori- 
ginatihg task unless modified in the ATTACH macro instruction. 

The originating task specifies the entry point of the program to be 
given control when the subtask begins execution. The specified entry 
point must be a member name or an alias in a directory of a partitioned 
data set, or it must have been specified in an IDENTIFY macro instruc- 
tion. If the specified entry point cannot be located, the new subtask 
is abnorinally terminated. The load module containing the program is 
brought into storage if a usable copy is not available. 

A linkage relationship is established between the originating task 
and the subtask by the task control block. The originating task can 
pass a parameter list to the subtask; it can also provide an event con- 
trol block in which termination of the new task is posted, and an exit 
routine to be given control upon subtask termination. The address of 
the task control block for the subtask is returned in register 1. 

ATTACH cannot be issued in a STAE exit routine. The program issuing 
ATTACH must not terminate before all its subtasks have terminated. 

For systems with the time-slicing option, the dispatching priority 
determines whether the new task will participate in tine-slicing. The 
new task executes asynchronously to the calling task, but within the 
same partition. 

For systems with the dynamic dispatching option, if the attaching 
task is in the dynamic dispatching group, the subtask is also put in the 
dynamic dispatching group. If the attaching task is not in the dynamic 
dispatching group, the subtask will not be in the dynamic dispatching 
group. If the subtask 's resultant dispatching priority equals that of 
the dynamic dispatching group, it is put on the ready queue immediately 
in front of the dynamic dispatching group. 

Write the standard form of the ATTACH macro as follows. Information 
about the list and execute forms follows this description. 

T ■ T ■ ■ — -T • • ■ — T . 

j [symbol] {ATTACH | (EP=symbol \ I 

I < EPLOC= address of name ( I 

I (DE=address of 4ist entry) I 

I [,pCB=dGb address] | 

I [,PARAM=(addresses) t,VL-l]] | 

I [ ,ECB=ecb address] I ,ETXR=exit routine address] | 

I t,LPMOD=nuir.ber] t ,DPMOD=number] | 

I ( YES \ iYES X I 

I [ ,TQE=\NO i t ,FPREGSA= INO fl | 



EP= 

is the entry name in the load module to be given control. 

[ ] indicates optional name or operand; select one from vertical stack 
with { }. 
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ATTACH 



EPLOC= 

is the virtual storage address of the entry name. Pad the name 
with blanks to eight bytes, if necessary. 

DE= 

is the address of the name field of a 58-byte list entry for the 
entry name. The list entry is constructed using the BLDL macro 
instruction. The DCB operand must indicate the same data control 
block used in the BLDL macro instruction. 

DCB= 

is the address of the data control blcck for the partitioned data 
set containing the entry name. Specifying an address of zero or 
omitting the^ DCB operand indicates the data set is in the link 
library or the job step library. 

PARAM= 

is one or more address parameters, separated by commas, to be 
passed to the called program. Each address is expanded inline to a 
fullword on a fullword boundary, in the order designated. Register 
1 contains the address of the first parameter when the program is 
given control. If this operand is omitted, register 1 is not 
altered. 

VL=1 

is written as shown. Use it only if PARAt^ is designated, and only 
if the called program can be passed a variable number of parame- 
ters- VL=1 causes the high-order bit of the last address parameter 
to be set to 1; the bit can be checked to find the end of the list. 

ECB= 

is the address of an event control block (fullword on a fullword 
boundary) to be used by the control program to indicate the ter- 
mination of the new task- The return code (if the task is ter- 
minated normally) or the completion code (if the task is terminated 
abnormally) is also placed in the event control block. If you code 
this operand, you must also issue a DETACH macro instruction to 
remove! the subtask from the system after the subtask has been 
terminated. 

ETXR= 

is the address of the end-of-task exit routine to be given control 
after the new task is normally or abnormally terminated. The exit 
routine is given control when the originating task becomes active 
after the subtask is terminated, and must be in virtual storage 
when required. If the same routine is used for more than one sub- 
task, it must be reenterable. If you code this operand, you must 
also issue a DETACH macro instruction to remove the subtask from 
the system after the subtask has been terminated. 

The contents of the registers when the exit routine is given con- 
trol are as follows: 



R egister Contents 

0 Control program information. 

1 Address of the task control block for the task that was 
terminated. 

2-12 Unpredictable. 

13 Address of a save area provided by the control program. 

lU Return address (to the control program). 

15 Address of the exit routine. 
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!Ehe exits routine is responsible for saving and restoring the regis- 
ters. It operates Xogically as a subroutine and- must return con- 
trpX to the Gontroli programs 

LI>MGD= 

is the number to be subtracted from the current limit priority of 
the originating task. The result is the limit priority of the new 
task. If omitted, the current limit priority of the originatihg 
task is assigned as the liroit priority of the new task. 

DPMGD- 

is the signed number to be algebraically added to the current dis- 
patching priority of the originating task. The result is assigned 
as the dispatching priority of the new task, unless it is greater 
than the liroit priority of the new task. If the result is greater, 
the limit priority is assigned as the dispatching priority. If you 
specify a register, a negative number must be in two's complement 
form in the register. If you omit this operand, the dispatching 
priority assigned is the smaller of either the new task's limit 
priority or the originating task's dispatching priority. 

Note s The LPMOD. and DPMOD parameters are ignored for attaching tasks 
that are within the dynamic dispatching group. 

TQE=fYES) 

Vno j 

specifies whether a Timer Queue Element (TQE) is to be created for 
the new subtask. Specify TQE=NO if the subtask and all routines 
invoked by that subtask are not dependent on timer interrupts. 
Each TQE=NO results in a savings of 112 bytes of fixed PQA- If 
this operand is omitted, YES is assumed. 

FPREGSA=/YES) 
VNO / 

specifies whether a floating-point register save area is to be 
created for the subtask. Specify FPREGSA=NO if the subtask and all 
routines invoked by that subtask do not use the Floating Point 
Instruction Set. Each FPREGSA=s^NO results in a savings of 32 bytes 
of fixed PQA- If this operand is omitted, YES is assumed. 
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ATTACH — Create a New Task (VS2) 

The ATTACH macro instruction causes the control program to create a 
new task and indicates the entry point in the program to be given con- 
trol when the new task becomes active. The entry point ncune that is 
specified must be a member name or an alias in a directory of a parti- 
tioned data set, or must have been specified in an IDENTIFY macro 
instruction. If the specified entry point cannot be located , the new 
subtask is abnormally terminated. 

The address of the task control block for the new task is returned in 
register 1. The new task is a subtask of the originating task; the ori- 
ginating task is the task that was active when the ATTACH macro instruc- 
tion was issued. The limit and dispatching priorities of the new task 
are the same as those of the originating task unless modified in the 
ATTACH macro instruction. The dispatching priority determines whether 
or not the new task participates in time slicing or in the APG (automat- 
ic priority group) . 

The load module containing the program to be given control is brought 
into virtual storage if a usable copy is not available in virtual 
storage. The issuing program can provide an event control block, in 
which termination of the new task is posted, an exit routine to be given 
control when the new task is terminated, and a parameter list whose 
address is passed in register 1 to the new task. If the ECB or ETXR 
operands are coded, a DETACH macro instruction must be issued to remove 
the subtask from the system before the program that issued the ATTACH 
macro instruction terminates. If the ECB or ETXR operands are not 
coded, the subtask is automatically removed from the system upon comple- 
tion of its execution. The ATTACH macro instruction cam also be used to 
specify that ownership of virtual storage subpools is to be assigned to 
the new task, or that the subpools are to fce shared by the originating 
task and the new task. 

The ATTACH macro instruction cannot be issued in a STAE exit routine - 
The program issuing the ATTACH macro instruction must not terminate 
before all of its subtasks have terminated. 

For further discussions of time slicing and the use of an existing 
copy of a load module, refer to Part I. 

The standard form of the ATTACH macro instruction is written as 
follows: 
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ATTACH 

[ tsyrobol] | ATTIkCH I ^EP=^toQa v (,DCB=dcb address] ] 

I t i IsPlOC^owldte^sa Qf name V I 

1 ■ ■ I . I WMF^m^^m^. list entry i [ 

i I I I 

I I t CfclI*«€«iKnaainfc€?c* ErPPMO^^^umberl | 

I I I; |,|»AlU^(ad^tPses>r^ I 

I; \ I trlCBF^icla ad<ir@ssJC,:^XR=exit routine address] | 

ft i I 1 

I I I r^GSPV=nwTOJber n r, sjasi>^nurober 1| 

I i I t^^itrsadi^essjs ©f lisctj; [^3HStl#-address of listj j 

I I t I 

I I I iim\ I 

I ^ I ■ I 

I I I [,TASKI,IB=dct> address} j 

I I I I 

I I I [ , STAI= (exit address I! , parameter list address ] ) 3 | 

I I I I 

i I I cmm I I 

I I I (HALT > /YESi I 

\ I I t ,PqRGE=> QUIESCEB [,ASYNCH=\Np fJ j 



EP= 



is the entry name in the load module to be given control. 



DCB= 



EPLOC= 

is the virtual storage address of the entry name. The name must be 
padded with blanks to eight bytes , if necessary. 

DE= 

is the address of the name field of a list entry for the entry 
name. The list entry is constructed using the 6LDL macro instruc- 
tion. The DCB operand must indicate the satme data control block 
used in the BXJPXi. macro instruction. 

is the address of the data control block for the partitioned data 
set containing the entry name. The address of the data control 
block for either the link or job library is designated by specify- 
ing an address of 0 or by omitting the DCB operand. 

LPMOD= 

is the number to be subtracted from the current limit priority of 
the originating task. The result is the limit priority of the new 
task. If omitted, the current limit priority of the originating 
task is assigned as the limit priority of the new task. 

DPMOD= 

is the signed number to be algebraically added to the current dis- 
patching priority of the originating task. The result is assigned 
as the dispatching priority of the new task, unless it is greater 
than the limit priority of the new task. If the result is greater, 
the limit priority is assigned as the dispatching priority . 



[ 1 indicates optional name or operand; select one from vertical stack 
within { }; select on.e or none from vertical stack within (1. 
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If a register is designated, a negative number inust be in two's 
complement form in the register. If this operand is omitted, the 
dispatching priority assigned is the smaller of either the new 
task's limit priority or the originating task's dispatching 
priority. 

PARAM= 

is one or more address parameters, separated by commas, to be 
passed to the called program. Each address is expanded in line to 
a fullword on a fullword boundary, in the order designated. 
Register 1 contains the address of the first parcuneter when the 
program is given control. If this operand is omitted, register 1 
is not altered. 

VL=1 

is written as shown- It can be designated only if PARAM is desig- 
nated, and should be used only if the called program can be passed 
a variable number of parameters. VL=1 causes the high~order bit of 
the last address parameter to be set to 1; the bit can be checked 
to find the end of the list. 

ECB= 

is the address of an event control block to be used by the control 
program to indicate the termination of the new task. The return 
code (if the task is terminated normally) or the completion code 
(if the task is terminated abnormally) is also placed in the event 
control block. If this operand is coded, a DETACH ionacro instruc- 
tion must be issued to remove the subtask from the system after the 
subtask has been terminated. 

ETXR= 

is the address of the end-of-task exit routine to be given control 
after the new task is normally or abnormally terminated. The exit 
routine is given control when the originating task becomes active 
after the subtask is terminated, and must be in virtual storage 
when required. If the same routine is used for more than one sub- 
task, it must be reenterable. If this operand is coded, a DETACH 
macro instruction must be issued to remove the subtask from the 
system after the subtask has been terminated. The contents of the 
registers when the exit routine is given control are as follows: 

Register Contents 



0 Control program information. 

1 Address of the task control block for the task that was 
terminated. 

2-12 Unpredictable. 

13 Address of a save area provided by the control program. 

14 Return address (to the control program) . 

15 Address of the exit routine. 



The exit routine is responsible for saving and restoring the 
registers. 

GSPV= 

is a virtual storage subpool number. Ownership of the specified 
virtual storage subpool is assigned to the new task. Programs of 
the o^riginating task can no longer use the associated virtual 
storage area. 
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GSPlr= 

is the address of a list of virtual storage subpool numbers. The 
first byte of the list contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage 
subpool number. Ownership of each of the specified virtual storage 
subpools is assigned to the new task. Programs of the originating 
task can no longer use the associated virtual storage areas. 

SHSPV^ 

is a virtual storage subpool number. Programs of both the ori- 
ginating task and the new task can use the associated virtual 
storage area. 

SHSPL= 

is the address of a list of virtual storage subpool nimabers. The 
first byte of the list contains the number of remaining bytes in 
the list; each of the following bytes contains a virtual storage 
subpool number. Programs of both the originating task and the new 
task can use the associated virtual storage areas. 

SZERO=: 

is used to indicate whether subpool 0 is to be shared with the sub- 
task. YES specifies that subpool 0 is to be shared; NO specifies 
that subpool 0 is not to be shared. YES is assumed if this operand 
is omitted. 

TASKLIB= 

is used to indicate whether a task library DCB address has been 
supplied. If an address is supplied, it is stored in TCBJLB. 
Otherwise, TCBJLB is propagated from the originating task. 

STAI= 

is used to indicate whether a STAI SCB is to be created; any STAI 
SCBs queued to the originating task are propagated to the new task. 
The first address supplied should be the address of the STAI exit 
routine which is to receive control if the subtask abnormally ter- 
minates. The STAI exit routine must be in virtual storage at the 
time of abnormal termination. The second address is the address of 
a parameter list which may be used by the STAI exit routine. A BC 
(basic control) mode PSW is reflected in the STAE work area. 

PURGB= 

is used to indicate what action is to be taken with regard to I/O 
operations when the subtask is abnormally terminated. This operand 
is used only in conjunction with the STAI= operand. No action may 
be specified (NONE) , a halting of I/O operations may be requested 
(HALT), or a quiescing of I/O operations may be indicated 
(QUIESCE) . The meaning of the PURGED operand is exactly as speci- 
fied in the STAE macro description. If omitted, QUiESCE is 
assumed. 

ASYNCH^ 

is used to indicate whether asynchronous exits are to be allowed 
when a subtask ABEND occurs. This operand is used only in conjunc- 
tion with the STAI= operand. The meaning of the ASYNeH= operand is 
exactly as specified in the STAE macro description. If omitted, NO 
is assumed. 
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ATTACH — List For m 

Two parameter lists are used in an ATTACH macro instruction: a con- 
trol program parameter list and an optional problem prograir parameter 
list. You can construct only the control prcgrairi parameter list in the 
list form of ATTACH. Address parameters to be passed in a parameter 
list to the problem program can be provided using the list form of the 
CALL macro instruction. This parameter list can be referred to in the 
execute form of ATTACH. 



The description of the standard forir of ATTACH explains the function 
of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The operand coirbinations in 
the shaded area of the format description may only be used in ai VS2 sys- 
tem. The TQE and FPREGSA operands are only used in a VSl system. The 
format description below indicates the optional and required operands in 
the list form only. 



[symboll \ ATTACH \ i EP=symbol 

< EPLCC=address of name 
(DE=address of list entry 
l,DCB=dcb address] [, ECB=ecb address] 
[,ETXR=exit routine address] [ ,LPMOD=number] 
[ , DPMOD=nuinber ] , SF=L 

|YES) ( YES ) 
t,TQE=\NO / ] [,FPREGSA=\NO |] VSl only 

t,GBFV«nia»ber3 l^GJSPL^adiare^s of list! 
C,iSiaifi9?V«iia»iberH,SS$l?l*»««iar^^ of list J 

f YES t 

l^StBRO^'^KO /3 J[,l:ASKlXB«acb address! 

(mm ) 



symbol 

is any symbol valid in the assembler language. 

address 

is any address that may be written in an A-type address constant, 
number 

is any absolute expression valid in the assembler language. 



SF=L 



indicates the list form of ATTACH. 



[ ] indicates optional name or operands; select one from vertical stack 
within { >. 
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ATTACH Execute Form 

Two parameter lists are used in ATTACH: a control F^^ogrann parameter 
list and an optional problem program parameter list. Either or both of 
these parameter lists can be remote and can be referred to and modified 
by the execute form of ATTACH. If only the problem program parameter 
list is remote, operands that require use of the control program para- 
meter list cause that list to be constructed inline as part of the macro 
expansion. 

The description of the standard form of ATTACH explains the function 
Of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The operand combinations in 
the shaded area of the format descriptions may only te used in a VS2 
system. The TQE and FPREGSA operands are only used in a VSl system. If 
specified in the list form, you need net respecify them in the execute 
form. The format description below indicates the optional and required 
operands in the execute form only. 



(symbol] 



ATTACH 



(EP=symbol \ 
< EPLOC=address of name \ 
(DE=address of list entry) 
(,DCB=dcb address] 
[, PARAM=( addresses ) (,VL=1]] 

[,ECB=ecb address] [, ETXR=exit routine address] 
[, LPMOD=n umber ][, DPMOD=number ] 

(YES) f Y£S \ 
(,TQE=1nO ( ] I,FPPEGSA= (NC h VSl only 
,MF= (E, jprobiem program list addressO 

\ (1) I 

,SF=CE, /control program list address^) 

1 (15) i 

,MF=(E, laddressi ) ,SF= (E, (address ( ) 
I (1) I \ (15) j 



p^l^^Siiipiiliiiiiiiiiiiiii^^ 

piPliilM 



symbol 

is any symbol valid in the assembler language, 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. You may specify the register symbolically or with 
an absolute expression; always code it within parentheses. 

number 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. You may specify the register symbolically or 
with an absolute expression; always code it within parentheses. 



I ] indicates optional name or operand; select one from vertical stack 
within { } . 
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MF=(E, j problem program list address U 

\ (1) / 

indicates the execute form of the macro instruction using a remote 
problem program parameter list . Any control program parameters 
specified are provided in a control program parameter list expanded 
inline. If you also specify PARAK, the address parameters are 
placed on contiguous fullword boundaries, beginning at the address 
specified in the MF opercind and sequentially overlaying correspond- 
ing fullwords in the existing list. The address of the problem 
program parameter list can be coded as described under "address," 
or can be loaded into register 1, in which case MF=(£, (D) should 
be coded. 

SF=(E, (control program list address U 
I (15) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list . Any problem program parameters 
specified are provided in a problem program parameter list expanded 
in line. The address of the control program parameter list can be 
coded as described under "address," or can be loaded into register 
15, in which case SF=(E, (15)) should be coded. 

MF=(E, /address \) , SF=(E,/ address U 
\ (1) / \ (15) / 

indicates the execute form of the macro instruction using both a 
remote problem program parameter list and a remote control program 
parameter list. The addresses of the parameter lists are coded or 
loaded into registers 1 and 15, as explained above. 
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CALL — Pass Control to a Control Section 



CALL 



CALL passes control to a control section at a specified entry point 
as follows: 

• OVERLAY ; The overlay segment containing the designated entry point 
is brought into virtual storage if required, and control is passed 
to the segment. (15) must not be designated in an exclusive call. 
Refer to Linkage Editor and Loader for details on overlay. The CALL 
macro instruction cannot be used in an asynchronous exit routine. 

• NON- OVERLAY; If a symbol is designated, the linkage editor includes 
the load module containing that entry point in the same load module 
containing the CALL instruction. When the CALL macro instruction is 
executed, control is passed to the control section at the specified 
entry point. If (15) is designated, the load module containing the 
entry point must be in virtual storage, and register 15 must contain 
the address of the entry point. 

The linkage relationship established when control is passed is the 
same as that created by a BAL instruction; that is, the issuing program 
expects control to be returned. The control program is not involved in 
passing control, so the reusability of the called program roust be main- 
tained by the user. 

An address parameter list can be constructed and a calling sequence 

identifier can be provided. The standard form of the CALL macro 

instruction is written as follows. Information about the list and 
execute forms follows this description. 



I [symbol] \ CALL j (entry point nameH , (address parameters) C ,VL] ] | 

I III (15) / I 

I I I (,ID=number] j 

L X JL " . . J- ■ 

entry point name 

is the name of the entry point to be given control; the name is 
used in the macro instruction as the operand of a V-type address 
constant; before execution it must be resolved to a virtual address 
by linkage editing. If (15) is designated, register 15 must con- 
tain the address of the entry point to be given control. 

address parameters 

are one or more address parameters, separated by commas, to be 
passed to the called program. Each address is expanded, in the 
order designated, to a f ullword oii a f ullword boundary. When con- 
trol is passed, register 1 contains the address of the first param- 
eter. If no address parameters are designated, the contents of 
register 1 are not changed. 

VL 

is written as shown. It can be designated only if address parame- 
ters are designated. Use it only when a variable number of parame- 
ters can be passed to the called program. VL causes the high-order 
bit of the last address parameter in the macro expansion to be set 
to 1; the bit can be checked by the called program to find the end 
of the list . 



[ ] indicates optional name or operand; select one from vertical stack 
within { }. 
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CALL 



maximum value is l^^-l. The last fullword of the macro expansion 
is a NOP instruction containing the ID value in the low-order two 
bytes. When the called program is given control, the address 
resides at 2 bytes past the location pointed to by register 14. 

Upon entry to the called program, register contents are as follows: 

Register Contents 

1 Address of parameter list if present. 

14 Return address. 

15 Entry point of called program. 
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CAIiL — List Form 

The list form of the CAItli macro ixirStruction is nse^ to construct a 
nonexecutable problem program parameter list. This list form g^erates 
only ADGONs of the address parameters. This problem program parameter 
list ccm be referred to in the escecute form of a CALL, LINK, ATTACH, or 
XCTL macro instruction. 

The description of the standard form of the CALL macro instruction 
explains the function of each operand. The description of the standard 
form also indicates which operands are always optional and which are 
required in at least one of a pair of list and execute forms. The for- 
mat description below indicates the optional and required operands in 
the list form only. The comma before the parenthesis must be coded to 
indicate tbe absence of the entry name operand, which is not allowed in 
the list form. 

[ [symbol] | CALL | , (address parameters) (,VL] ,MF-L | 
symbol 

is any symbol valid in the assembler language • 
address 

is any address that may be written in an A-type address constant. 

MF=L 

indicates the list form of the CALL macro instruction. 



[ I indicates optional name or operands. 
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CALL — Execute Form 



A remote problem program parameter list is referred to and can be 
modified by the execute form of the CALL macro instruction. Only 
executable instructions and a VCON of the entry point are generated. 

The description of the standard form of the CALL macro instruction 
explains the function of each operand. The description of the standard 
form also indicates which operands are always optional and which are 
required in at least one of the pair of list and execute forms. The 
format description below indicates the optional and required operands in 
the execute form only. 



1 [symbol] | CALL j (entry point name H , (address parameters) 1 C,VL] | 



name, symbol 

is any symbol valid in the assembler language. 

address 

is any address of an existing address constant that is valid in an 
RX-type instruction, or one of general registers 2 through 12, pre- 
viously loaded with the indicated address. The register may be 
designated symbolically or with an absolute expression, and is 
always coded within parentheses. 

number 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. The register may be designated symbolically 
or with an absolute expression, and is always coded within 
parenthes es . 

MF=(E, (problem program list address^) 



indicates the execute form of the macro instruction using a remote 
problem program parameter list. The address of the problem program 
parameter list can be coded as described under "address," or can be 
loaded into register 1, in which case code MF- (E, (1) ) . Register 1 
or the problem program list address must point to the list form of 
CALL. If the address parameter is also specified, the ADCCNs of 
the parameter are placed on contiguous fullword boundaries begin- 
ning at the address specified* in the MF operand, and sequentially 
overlaying corresponding full words in the existing list. 



[ ] indicates optional name or operand; select one from vertical stack 
within { }. 




L. 



.X J 



(1) 
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CHAP — Change Dispatching Priority 

CHAP ehanges the dispatching priority of the task or any of its sub- 
tasks. CHAP may also change the limit priority of a subtask. (See the 
section "Priority of Subtasks* in this publication. The algebraic sum 
of the priority change value and the dispatching priority of the subject 
task determines the new dispatching priority. 

• If the subject task is the task executing CHAP, its dispatching 
priority is set equal to the sum of the priority change value and 
the dispatching priority. This value is not set at less than zero 
or greater than the limit priority for the task. Its limit priority 
is unaffected. 

• If the subject task is a subtask of the task executing CHAP, its 
dispatching priority is set equal to the sum of the priority change 
value and the dispatching priority. This value is not set at less 
than zero or greater than the limit priority of the task executing 
CHAP. After this modification, if the subtask 's dispatching priori- 
ty exceeds its limit priority, the limit priority is made equal to 
the dispatching priority. 

Notes ; The limit priority of the job step task depends on the PRTY pa- 
rcumeter of the JOB statement. The dispatching priority of any task 
determines whether or not the task participates in time slicing (applic- 
able when the operating system includes the time-slicing option). For 
more details, refer to Time Slicing in the Services section. 

If the CHAP issuer is in the dynamic dispatching group, the CHAP 
request is ignored. If the CHAP issuer is not in the dynamic dispatch- 
ing group, and the resultant dispatching priority for the CHAPed task is 
equal to the dispatching priority of the dynamic dispatching group, the 
CHAPed TCB is moved in the ready queue to the position immediately in 
front of the dynamic dispatching group. You may not CHAP into, or out 
of a dynamic dispatching group. 

The standard form of CHAP is written as follows : 

r- ' T- "-"T " ■ • 1 ■ 

I [symbol] | CHAP | priority change value r,tcb location address"] | 



priority change value 

is the signed value to be added to , the dispatching priority of the 
specified task. If the value is negative and contained in a 
register, it should be in two's complement form. 

tcb location address 

specifies the address of a fullword on a fullword boundary contain- 
ing the address of a task control block for a subtask of the active 
task. The address of the task control block is an output of the 
ATTACH macro. *S' indicates that the priority of the active task 
is to be changed. "S* is assumed if the operand is omitted or if 
it is coded to specify a zero address. 



[ ] indicates optional name or operand; select one or none from vertical 
stack within (3; ; indicates an assumed value- 



L. 



.X. 
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DELETE — Relinquish Control of a Load Module 

DELETE cancels the effect of a previous LOAD macro instruction. If 
DELETE cancels the only outstanding LOAD request for the module and no 
other requirements exist for the module, the virtual storage occupied by 
the load module is released and is available for reassignment by the 
control program. The name specified in DELETE must be the same as that 
specified in the LOAD macro instruction that brought the load module 
into storage; it must be issued by the same task that issued the LOAD 
macro instruction. 

The DELETE macro is written as follows: 

r T T 1 

i [symbol] | DELETE | (EP^symbol \ | 



is the address of the entry name described above. Pad the name 
with blanks to eight bytes, if necessary. 

DE= 

is the address of the name field of a 58-byte list entry for the 
entry name described above, constructed using the BLDL macro 
instruction. 

When control is returned, register 15 contains a 0 if the operation 
was completed successfully. Register 15 contains a 4 if a LOAD was not 
issued for the task issuing the DELETE instruction or if the responsibi- 
lity count had previously become zero. 



[ ] indicates optional name; select one frcm vertical stack within £ }. 




EP= 



is the entry name used in the associated LOAD macro instruction. 



EPLOC= 
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DEQ — Release a Serially Reusable Resource 

DEQ removes control of one or more (maximum is 255) serially reusable 
resources from the active task. It can also be used to determine wheth- 
er control of the resource is currently assigned to or requested for the 
active task. Register 15 is set to 0 if the request is satisfied. An 
unconditional request to release a resource from a task that is not in 
control of the resource, or a request that contains an invalid address 
of a resource results in abnormal termination of the task. 

The standard form of the DEQ macro instruction is written as follows. 
Information about the list and execute forms follows this description. 

r T 1 1 

I [symbol] |DEQ| (qnante address, rname address, trname length] , [STEP "],...) | 



gname address 

is the address in virtual storage of an eight-character name 
(padded with blanks on the right if necessary) . Every program 
issuing a request for a serially reusable resource must use the 
same qname and rname to represent the resource. The name should 
not start with SYS, so that it will not conflict with system names. 
The name must be the same qname previously specified for the 
resource in an ENQ macro instruction. 

rname address 

is the address in virtual storage of the name used in conjunction 
with the qname to represent the resource acquired by a previous ENQ 
macro instruction. The ncime can be qualified and must be from 1 to 
255 bytes long. 

rname length 

is the length of the rname described above. The length must have 
the same value as specified in the previous ENQ macro instruction. 
If the operand is omitted, the assembled length of the rname is 
used. You can specify a value between 1 and 255 to override the 
assembled length, or a value of 0. If you specify G, the length of 
the rname must be contained in the first byte at the rname address 
designated above. 

STEP or SYSTEM 

is written as shown. You musit specify the same STEP or SYSTEM 
option as you used in the ENQ macro instruction requesting the 
resource. You can specify up to 255 resources. 

RET=HAVE 

is written as shown. It specifies that the request for releasing 
the resources named in DEQ is to be honored only if the active task 
has been assigned control of the resources- If the operand is 
omitted, the request for release is unconditional, and the active 



£ ] indicates optional name or operand; select one or none from vertical 
stack within t 3 . , . . . indicates that more than one resource can be 
specified in the DEQ macro instruction, to a maximum of 255. 




I [,RET=HAVE] 



L. 



.X. 



-J 
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DEQ 

task is abnormally terminated if it has been assigned control of 
the resources. The results of conditional requests are indicated 
by the return codes shown in Figure 52. 

Return codes are provided by the control program only if RET=HAVE is 
designated. If all of the return codes for the resources named in DEQ 

are 0 register 15 contains 0. If any of the return codes are not 0 
register 15 contains the address of a virtual storage area containing 
the return codes as shown in Figure 53. The return codes are placed in 
the parameter list resulting from the macro expansion in the same 
sequence as the resource names in the DEQ macro instruction. The return 
codes are shown in Figure 52. 




Meaning 



The resource has been released. 

The resource has been requested for the task, but the task 
has not been assigned control. The task is not removed from 
the wait condition. (This return code could result if DEQ is 
issued within an exit routine which was given control because 
of an interruption.) 

Control of the resource has not been requested by the active 
task, or the resource has already been released. 



Figure 52- DEQ macro instruction return codes 



Address 
Returned in 
Register 15 



Return 
Codes 




Retxirn codes are 12 
bytes apart, starting 3 
bytes from the address 
in register 15. 



Return code area used by DEQ 
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DEQ — List Form 

use the list form of DEQ to construct a control program parameter 
list* You can specify any number of resources in DEQ; therefore, the 
nunnber of qname and rnane combinations in the list form of DEQ must be 
equal to the maximum number of qname andi rname combinations in any 
execute form of DEQ that refers to that list form - 

The description of the standard form of the DEQ macro instruction 
explains the function of each operand. The description of the standard 
form also indicates which operands are always optional and which are 
required in at least one of the pair of list and execute forms. The 
formiat description below indicates the optional and required operands in 
the list form only. 



j [symbol] j DEQ j ( C qname address] , [rname address] , (rname length], j 
I j i rSYSTEMl, . ..) t,RET=aAVE3,MF=L | 

[ i 1 ^^^^ J I 

symbol 

is any symbol valid in the ass<^bler language, 
address 

is any address that may be written in an A-type address constant . 
length 

is any absolute expression valid in the assembler language. 

MF=L 

indicates the list form of the DEQ macro instruction. 



( ] indicates optional nctme or operand; indicates that more than 

one qname and rname condDination with associated options can be coded. 
Select one or none fr<m vertical st^ck within i 3. 
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DEQ — Execute Form 

A remote control program parameter list is used in, and can be modi- 
fied by, the execute form of the DEQ macro. The parameter list can be 
generated by the list form of either the DEQ or the ENQ macro 
instruction. 

The description of the standard form of DEQ explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which operands are required in at least 
one of the pair of list and execute forms. The format description below 
indicates the optional and required operands in the execute form only. 







[symbol] | DEQ 1 [ ( (qname address] , [rname address] , [rname length] , 


1 1 ["SYSTEM 


,...)] r,RET=HAVE"| 


1 1 [step 


L, RET=NONE J 


1 1 ,MF=(E, 


control program list addressl) 




i (1) / 







symbol 

is any symbol valid in the assembler language. 



address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. You may designate the register symbolically or with 
an absolute expression; always code it within parentheses. 



length 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. You may designate the register symbolically 
or with an absolute expression; always code it within parentheses. 



RET=NONE 

specifies an unconditional request to release all of the resources - 
The request is processed as though no RET operand had been coded. 



MF= (E, (control program list address)) 

I (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list. Code the address of the control 
program parameter list as described under "address," or you can 
load the address into register 1, in which case you should code 

MF=(E, (1)). 



( ] indicates optional name or operand; select one from vertical stack 
within { }; indicates that more than one qname and rname combina- 

tion with associated options can be coded. Select one or none from 
vertical stack within [ ] . 
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DETACH — Delete a Subtask (VSl) 

DETACH removes a previously teirminat^d subtask froiti the system by 
releasing the storage containing the TCB (task control block) of the 
subtask. The subtask must be detached by the task that created it or by 
a task using the same TCB as the creating task, and the ATTACH macro 
instruction used to create the subtask must have specified the ECB or 
ETXr operand. You can issue a DETACH only for subtasks created by an 
active task. 

Ail subtasks created through execution of the ATTACH macro instruc- 
tion specifying ECB or ETXR must be detached before the originating task 
terminates. Failure to detach the subtasks results in abnormal termina- 
tion of the originating task when it attempts normal termination. If 
neither ECB nor ETXR is specified in the ATTACH macro instruction, 
DETACH should not be issued. 

If a DETACH is issued for a subtask that has not completed execution, 
that subtask and all its subtasks are abnormally terminated. If an ECB 
for recording the subtask' s teinnination is present, it is posted, but an 
ehd-of-task exit routine is ignored. Instead, the detaching task 
regains control at the next sequential instruction. 

If an invalid TCB address is passed to DETACH, the task that issued 
the DETACH is abnormally terminated. 

If a subtask was created by an ATTACH macro instruction that speci- 
fied the ECB operand, and the subtask has not yet terminated, DETACH 
abnormally terminates the subtask, specifies the completion code, and 
posts it in the ECB. 

If a subtask was created by an ATTACH macro instruction that did not 
specify ECB or ETXR, and the task has terminated, an attempt to detach 
the subtask results in abnormal termination of the task issviing DETACflS. 

The DETACH macro instruction is written as follows: 

r ' ■ -x-"*"^ ■ — T * ' 1 

I (symbol] | DETACH | tcb location address | 

L L ^ .^X . J ■ 

tcb location address 

is the virtual storage address of a fullword on a fullword boun- 
dary. The fullword contains the address of the task control block 
for the subtask to be removed from the system. The address of the 
task control block is an output of the ATTACH macro instruction. 



( i indicates optional name. 
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DETACH — Delete a Subtask (VS2) 

The DETACH macro instruction is used to remove from the system a sub- 
task created by an ATTACH macro instruction that specified the ECB or 
ETXR operand. Each subtask created in this manner must be removed from 
the system before the originating task terminates. Failure to remove 
these subtasks causes abnormal termination of the originating task and 
all of its subtasks. Issuing a DETACH macro instruction that specifies 
a subtask created without the ECB or ETXR operand also causes abnormal 
termination of the originating task when the specified subtask has 
already terminated. Issuing a DETACH macro instruction that specifies a 
subtask that has not terminated causes termination of that subtask and 
all of its subtasks. A DETACH macro instruction can be issued only for 
subtasks created by the active task. 

The DETACH macro instruction is written as follows: 

r T T 1 



tcb location address 

is the virtual storage address of a fullword on a fullword boun- 
dary. The fullword contains the address of the task control block 
for the subtask to be removed from the system. 



YES 

indicates that the exit routine specified in a STAE macro instruc- 
tion issued by the subtask is to be given control if the subtask is 
scheduled for abnormal termination while it is being detached. If 
a retry routine is specified by the STAE exit routine, it is not 
given control. 

NO 

indicates that the exit routine specified in the STAE macro 
instruction will not be given control if the subtask is scheduled 
for abnormal termination (ABEND) while it is being detached. If 
neither YES nor NO is specified, NO is assumed. 

When control is returned, register 15 contains one of the following 

return codes : 

Hexadecimal 

Code ' Explanation 

00 Successful completion. 

04 Incomplete subtask detached; STAE exit taken. 



I [symbol] | DETACH | tcb location address 

L X . X 




.J 



STAE= 
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DOM — Delete Operator Message (MCS with DIDOCS only) 

The DOM macro instruction deletes a message or group of messages from 
display on the display operator console. When a program no longer 
requires that a message be displayed, issue a DOM macro instruction to 
delete the message. 

Depending on the timing of ithe DOM relattive to the WTO (li) , tthfe mes- 
sage ^anay or may not be displ^iye^ . Wf the msessage is beiiig displayed, it 
is removed iiWsen spac^ 

When a WTO or WTOR macro instruction is executed, the Gcmtrol program 
assigns an identif ication number to ^the message. The control program 
returns the a£isi;gned identificatiOnsiMiiiiber C2U bits and right- justified) 
to the Issuing ^program in ^general *resgp.5Ster 1- 14hen display of the mes- 
sage is no longer need^, the DOM maiqro instruction shoulcl be coded 
using the ictentlficatiOn ymiuQber that ^was retiirned in generail register 1, 

The DOM macro instruction is written as follows: 

r ^T* T— — -^—^-1 

I [symbol] | DOM | /MSG=register \ j 



MSG= 

specifies a general register from 1 through 12 that contains the 
24-bit, right- justified identifiGation number of the message to be 
deleted. Use this operand to delete a single message. If you use 
register 1, the macro expansion is shortened by two bytes. 



specif ies the address Of a list of one or more fullwords, each word 
containing a 2U-bit, right- justified identification number of a 
message to be deleted. A maximum of 60 identification numbers may 
be in the message list. If more than 60 identification numbers are 
in the list, only the first 60 are processed. Begin the list on a 
fullword boundary. Indicate the end of the list by setting the 
high-order bit of the last ' f ull^^ord entry to 1 . If you use regist- 
er 1, the macro ^pansion is If any 
register 2 through 12 is used, the ^acro expansion is shortened by 
two bytes . 



[ ] indicates Optional rnsume; select one "f rom the vertical stack within 




MSGI.IST= 
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DXR — Divide Extended Register 

Use the DXR macro instruction to divide one extended- precision 
floating-point number by another. A detailed description of the divi- 
sion process and extended precision and rounding is given in IBM System/ 
370 Principles of Operation . 

To use the DXR macro instruction, you must provide a SPIE exit rou- 
tine to process the program exception caused (intentionally) by execu- 
tion of the DXR instruction. The SPIE exit routine is described in the 
section on Extended-Precision Floating-Point Simulation in the Services 
section of this publication. 

The DXR macro instruction is written as follows: 

r T T 1 

I [symbol] | DXR | regl,reg2 | 

L L JL J 



regl 

is the register that contains the dividend. The quotient is placed 
in this register; the remainder is discarded. 

reg2 

is the register that contains the divisor. 

Notes: Following is a list of limitations that apply to both the regl 
and the reg2 operand: 

• Registers 0 and 4 are the only registers that can be specified. 
However, you can specify them in either order. 

• Specify registers as decimal digits 0 or 4 or as symbols that have 
been equated to these decimal digits. 

• Never code these registers within parentheses. 



( ] indicates optional name. 
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ENQ — - Request Control of a Serially Reusable Resource 

ENQ requests the control program to assign control of one or itiore (up 
to 255) serially reusable resources to the active task. If any of the 
resources are not available, the active task is placed in a wait condi- 
tion imtil all of the requested resouroes are eivailable. Once control 
of a resource has been assigned to a task, it reiaains with that task 
until one of the programs of the same task issues a DEQ macro instruc- 
tion specifying the same resource* Register 15 is set to 0 if the requ- 
est is satisfied. 

You can also use ENQ to determine the status of the resource: wheth- 
er it is immediately available or in use, and whether control has been 
previously requested for the active task in another ENQ macro 
instruction. 

You may request either shared or exclusive use of a resource. The 
resource is represented in ENQ by a pair of names, the qname and the 
rname. The control program does not correlate the names with the actual 
resource. The relation of the name to the actual resource is your 
responsibility; ENQ simply coordinates access to whatever it is the 
names represent. The names may be given meaning restricted to a job 
step or across job steps. In either case, all programs for which coor- 
dination of the resource is provided must represent it by the same name. 

Issuing two ENQ macro instructions for the same resource without an 
intervening DEQ macro instruction results in abnormal termination of the 
task, unless the second ENQ designates RET=TEST, USE, CHNG, or HAVE. If 
normal termination of a task is attempted while the task still has con- 
trol of any serially reusable resources, or if resource input addresses 
are incorrect, the task is abnormally terminated. 

The standard form of the ENQ macro is written as follows. Informa- 
tion about the list and execute forms follows this description. 

r T T ■ — , 1 



I (symboll 



ENQ I (qname address , rname address , fEl , t rname length], 

LsJ I 

*,RET=TEST' 



I r SYSTEM] , . . . ) 
i I STEP J 



, RET^USE 
, RET=HAVE 
,RET=CHNG^ 



qname address 

is the address in virtual storage of an eight-character name. 
Every program issuing a request for a serially reusable resource 
must use the same qname and rname to represent the resource. The 
name should not start with SYS, so that it will not conflict with 
system names. 

rname address 

is the address in virtual storage of the name used in conjunction 
with the qname to represent a single resource. The name can be 
qualified and must be from 1 to 255 bytes long. 



C ] indicates optional name or operand; select none or one from vertical 
stack within [ 1; indicates that more than one resource may be 
specified in the ENQ maqro instruction, to a maximum of 255; indi- 
cates an assumed value. 
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is written as shown. It specifies that the request is for exclu- 
sive control of the resource. If you omit the operand, a request 
for exclusive control is assumed. If the resource is modified 
while under control of the task, the request must be for exclusive 
control. 



is written as shown. It specifies that the request is for shared 
control of the resource. If the resource is not modified while 
under control of the task, the request should bie for Shared 
control . 

rnarae length 

is the length of the rname described above. If you omit the 
operand, the assembled length of the rname is used. You can speci- 
fy a value between 1 and 255 to override the assembled length, or 
you may specify a value of 0. If 0 is specified, the length of the 
rname must be contained in the first byte at the rname address 
designated above, 

STEP 

is written as shown. It specifies that the resource is used only 
within the job step of the issuing program, and that a request for 
the same qname and rname from a program in another job step denotes 
a different resource. This option is assumed if the operand is 
omitted . 

SYSTEM 

is written as shown. It specifies that the resource may be used by 
programs of more than one job step, and that requests for the same 
qname and rname from programs of other job steps in the system 
denote the same resource. 

Because SYSTEM and STEP are opposite in meaning, both cannot refer 
to the same resource. If two macro instructions specify the same 
qname and rname, but one specifies SYSTEM and the other specifies 
STEP, they are treated as requests for different resources. Con- 
versely, when one resource is used by a single job step and another 
is used by several job steps, the same qname and rname can be used 
for both. 

RET= 

specifies a conditional request for all of the resources named in 
the ENQ macro instruction. If the operand is omitted, the request 
is unconditional. The results of a conditional request are indi- 
cated by the return codes described in Figure 54; the types of con- 
ditional requests follow, 

TEST - tests the availability of the resources but does not request 
control of the resources , 

USE - specifies that control of the resources be assigned to the 

active task only if the resources are immediately available. 
If any of the resources are not available, the active task 
is not placed in a wait condition. 

HAVE - specifies that control of the resources is requested only if 
a request has not been made previously for the same task. 

CHNG - specifies that the status of the resource specified is to be 
changed from shared to exclusive control. 
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Return codes are provided by the control prograin only if you specify 
RET=TEST, RET=USE, RET=CHNG, Or RET=HAVE; otherwise, return of the task 
to the active condition indicates that control of the resource has been 
assigned to the task. If all return codes for the resources named in 
the ENQ macro instruction are 0, register 15 contains 0. If any of the 
return codes are not 0, register 15 contains the address of a storage 
areai containing the return codeiSr as shown in Figure 55* The return 
codes aire placed in the parameter list resulting from the macro expan- 
sion in the same sequence as the resource names in the ENQ macro 
instruction. The return codes are shown in Figure 5U. 



12 
20 



Meaning j 

+ -T ' ..y ^— ^ . — . ~.| 

RET*=TEST I RisaSsUSE j RET=ERVE | RET^CHNG | 

I The resource is I control of the resource has | The status of j 
j immediately | been assigned to the active | the resource | 
I available. (task. |has been | 
I I I changed to | 
1 I j exclusive. | 
^ — . J. ^ ^ 

I The resource is not inonediately | — | The status can- 1 

I available. j j not be changed j 

i I I to shared. | 

|. .X ^ ^ 

I A previous request for control of the same |The resource j 
(resource has been made for the same task. Task (has not been i 
jhas control of resource. [queued. j 
y ^ -I 

I Resource is permanently unavailable. t 

I A previous request for control of the same |Not used. | 
(resource has been made for the same task. Taskj ( 
(does not have control of resource. j ( 

±. . . — J- J • 

Figure 54. ENQ return codes 



Address 

Returned in 
Register 15 



Return 
Codes 




Return codes are 12 
bytes apart, starting 3 
bytes from the address 
in register 15. 



Figure 55. Return code atrea used by ENQ 
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ENQ — List Form 

Use the list form of ENQ to construct a control program parameter 
list. Any number of resources can be specified in the ENQ macro 
instruction; therefore, the number of qname and mame combinations in 
the list form of the ENQ macro instruction must be equal to the maximum 
number of qname and mame combinations in any execute form of the macro 
instruction that refers to that list form. 

The description of the standard forir of ENQ provides the explanation 
the function of each operand- The description of the standard form also 
indicates which operands are always optional and which are required in 
at least one of the pair of list and execute forms. The format descrip- 
tion below indicates the optional and required operands in the list form 
only. 



[symbol] | ENQ | ( [qname 


address] , [mame 


address] , 


FeI , [mame length] , 

LsJ 


1 1 [system" 
j 1 [step 




-,fet=have" 
,ret=test 

,RET=USE 
, RET=CHNG_ 


,MF=L 





symbol 

is any symbol valid in the assembler language, 
address 

is any address that may be written in an A-type address constant, 
length 

is any absolute expression valid in the assembler language. 

MF=L 

indicates the list form of the ENQ macro. 



[ 3 indicates optional name or operand; indicates that more than 

one qname and rname combination with associated options can be coded; 

select one or none from vertical stack within [ ] ; indicates an 

assumed value. 
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ENQ - Execute Form 

A remote control program parameter list is used in, and can be modi- 
fied by, the execute form of the ENQ macro instruction. The parameter 
list can be generated by the list form of ENQ. 

The description of the standard form of ENQ provides the explanation 
the function of each operand. The description of the standard form also 
indicates which operands are always optional and which operands are 
required in at least one of the pair of list and execute forms. The 
format description below indicates the optional and required operands in 
the execute form only. 




C ( Iqnarae address] , trnaroe address] , rEl , [rname length! , 

[sj 

■,RET=HAVE'^ 



system] ,...)] 
STEP 



, RET=TEST 
, RET-USE 
,RET-CHNG 
, RET=NONE 



,MF=(E, (control program list addressV) 
\ (1) f 



symbol 

is any symbol valid in the assembler language, 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. The register may be designated symbolically or with 
an alDSolute expression; always code it within parentheses. 

loigtb 

is any al)solute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. The register may be designated symbolically 
or with an absolute expression, and is always coded within 
parentheses. 

RET=NONE 

specifies an unconditional request for control of all of the 
resources. The request is processed as though no RET operand had 
been coded. 

MF=(E, /control program list addressV) 
I (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list. The address of the control program 
parcuneter list can be coded as described under "address," or can be 
loaded into register 1, in which case code MF=:(E, (1)). 



[ 1 indicates optional name or operand; select one from vertical stack 
within { } ; , • • . indicates that more than one qname and and rname com- 
bination with associated options can be coded; select one or none from 
vertical staclc within [ ]; indicates an assumed value. 



112 



FREEMAIN 



FREEMAIN — Release Allocated Virtual Storage 

The FREEMAIN itiacro instruction releases one or more areas of virtual 
storage, or an entire virtual storage subpool, previously assigned to 
the active task as a result of a GETMAIN macro instruction. The active 
task is abnormally terminated if the specified virtual storage does not 
start on a double word boundary or if the specified area or subpool is 
not currently allocated to the active task. Register 15 is set to 0 to 
indicate successful completion. 

The standard form of the FREERAIN macro instruction is written as 
shown in the format description below. The operand combinations in the 
shaded area of the format description below must not be used in a VSl 
system; the job step would be abnormally terminated.. 







[symbol] | FREEMAIN | ) 


E,LV=number,A=address [ ,SP=number] \ 




1s!lBP»mmkmX':t * ' / 




iR,SP=(0) ( 




R,LV= (0) ,A= address ) 




|R,LV=(0) ,A=(1) I 




' R , LV=number , A=address ( , SP=number] i 




R, LV=number , A= (1) ( , SP=number] 1 




( V, A=address I , SP=number ] ' 


X J. . 





I Note: Only those operand combinations indicated above are valid. | 

L . J 



E 

(element) written as shown; specifies release of a single area of 
virtual storage allocated from the subpool indicated by the SP 
operand. The length of the virtual storage area is indicated by 
the LV operand; the address of the virtual storage area is provided 
at the address indicated in the A operand. 

L 

(list) written as shown; specifies release of one or more areas of 
virtual storage from the subpool indicated by the SP operand. The 
length of each virtual storage area is indicated by the values in a 
list beginning at the address specified in the LA operand. The 
address of each of the virtual storage areas must be provided in a 
corresponding list whose address is specified in the A operand. 
All virtual storage areas must start on a double word boundary. 

R 

(register) written as shown; specifies release of one area of vir- 
tual storage from the subpool indicated by the SP operand, or spe- 
cifies release of the entire subpool indicated by the SP operand. 
If the release is not for the entire subpool, the address of the 
virtual storage area is indicated by the A operand. The length of 
the area is indicated by the LV operand. The virtual storage area 
must start on a doubleword boundary. 

V 

(variable) written as shown; specifies release of one area of vir- 
tual storage from the subpool indicated by the SP operand. The 
address and length of the virtual storage area are provided at the 
address specified in the A operand. 



I ] indicates optional name or operand; select one from vertical stack 
within { }, 
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LV= 

lis the length, in bytes, of the virtual storage area being 
released. The value should be a multiple of 8; if it is not, the 
control program uses the next higher multiple of 8. If R is coded, 
LV=(0) may be designated; the high-order byte of register 0 must 
contain the subpool number, and the low-order three bytes must con- 
tain the length (in this case, the SP operand is invalied). 



is the virtual storage address of one or more consecutive full- 
words, starting on a fullword boundary. If the words are within an 
area to be released, they must be completely within the area and 
must not begin in the first two words of the first area. If E or R 
is designated, one word, which contains the address of the virtual 
storage area to be released, is required. If V is coded, two words 
are required; the first word contains the address of the virtual 
storage area to be released, and the second word contains the 
length of the area. If L is coded, one word is required for each 
virtual storage area to be released; each word contains the address 
of one virtual storage area. If R is coded, any of the registers 1 
through 12 can be designated, in which case the address of the vir- 
tual storage area, not the address of the fullword, must have pre- 
viously been loaded into the register. The specification of 
register 1 saves two bytes in the macro expansion. 

LA= 

is the virtual storage address of one or more consecutive fullwords 
starting on a fullword boundary. One word is required for each 
virtual storage area to be released; the high-order bit in the last 
word must be set to 1 to indicate the end of the list. Each word 
must contain the required length in the low-order three bytes. The 
fullwords in this list must correspond with the fullwords in the 
associated list specified in the A operand. If the words are 
within an area to be released, they must be completely within the 
area and must not begin in the first two words of the first area. 
The words must not overlap the virtual storage area specified in 
the A operand. 

SP= 

if the SP operand is optional (shown within brackets), it specifies 
the subpool number of the virtual storage area to be released. The 
subpool number can be between 0 and 127. If the SP operand is 
optional and is omitted, subpool 0 iS assumed. If the SP operand 
must be coded, it specifies the number of the subpool to be 
released, and the valid range is 1 through 127. Subpool 0 cannot 
be released. SP=(0) can be designated, in which case the subpool 
number must be previously loaded into the high-order byte of 
register 0; the three low-order bytes must be set to 0. 
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FREEMAIN — List Form 

Use the list form of the FREEMAIN macro instruction to construct a 
nonexecutable control program parameter list. Do not use the list and 
execute forms of the FREEMAIN macro instruction with the R-type (regist- 
er) of the macro instruction. 

The description of the standard form of FREEMAIN explains the func- 
tion of each operand. The description of the standard form also indi- 
cates which operands are always optional and which are reqiiired in at 
least one of the pair of list and execute forms. The opercind combina- 
tions in the shaded area of the format description may only be used in a 
VS2 system. The format description below indicates the optional and 
required operands in the list form only. 

r T r 1 

I [symbol] j FREEMAIN | ( [E] [ ,LV=number] [ , A=address] [, SP=niHnber] ){ 



I i I ( [V] [,A=address] [,SF=number] 

I I I MF=L I 
I. X X ^ 

I Note ; Only those operand combinations indicated above are valid.) 

L J 

symbol 

is any symbol valid in the assembler language, 
address 

is any address that may be written in an A-type address constant, 
number 

is any absolute expression valid in the assembler language. 

MF=L 

indicates the list form of the FREEMAIN macro instruction. 



( ] indicates optional name or operand; select one from vertical stack 
within { >. 
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FREEMAIN — Execute Form 

A remote control prograin para^neter list is used in, and can be modi- 
fied by, the execute form of the FREEISAIN macro instruction. The param- 
eter list can be generated by the list form of either a GETMAIN or a 
FREEMAIN. The list and execute forms of FREEMAIN cannot be used with 
the register (R) type of the macro instruction. 

The description of the standard foriri of FREEMAIN explains the func- 
tion of each operand. The description of the standard form also indi- 
cates which operands are always optional and which are required in at 
least one of the pair of list and execute forms. The operand combina- 
tions in the shaded area of the format description may only be used in a 
VS2 system. The format description below indicates the optional and 
required operands in the execute form only. 

r ' — " r T — -1 

I [symbol] | FREEMAIN | ( [E] (, LV=numberl [,A=address] [,SP=numher] (| 



I Note ; Only those operand combinations indicated above are valid.) 



is any symbol valid in the assembler language, 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. You may designate the register symbolically or with 
an ateolute expression; always code it within parentheses. 

number 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. You may designate the register symbolically 
or with an absolute expression; always eode it within parentheses. 



indicates the execute form of the macro instruction and specifies 
the address of a remote control program parameter list constructed 
by the list form of FREEMAIN. In the remote control program param- 
eter list, the operands for the execute form of FREEMAIN overlay 
the operands specified by the list form* 



t ] indicates optional name or operand; select one from vertical stack 
within { > . 




L. 



J 



symbol 




il6 



GETMAIN 



6ETMAIN — Allocate Virtual Storage 

The GETMAIN macro instruction requests the control program to alloc- 
ate one or more areas of virtual storage to the active task. The virtu- 
al storage areas are allocated from the specified subpool in the virtual 
storage area assigned to the associated job step. The virtual storage 
areas each begin on a doubleword or page boundary and are not cleared to 
0 when allocated. The total of the lengths specified must not exceed 
the length available to the job step. The virtual storage areas are 
released when the task assigned ownership terminates, or through the use 
of the FREEMAIN macro instructions. 

The control program does not use the virtual storage area of the 
address in register 13 as a save area when processing release requests, 

if R is coded- 

The standard form of the GETMAIN macro instruction is written as 
shown in the format description below. The operand combinations in the 
shaded area of the format description below must not be used in a VSl 
system; the job steps would be abnormally terminated. 



[symbol] j GETMAIN 



EC, LV=number,A=address t ,SP=number] 
EU , LV=number , A=address ( , SP=number ] 

I R,LV= number, ( ,SP= number] 
'r,LV=(0) 

VC , LA=address , A=address [ , SP=number] [", BNDRY=( DBLWD ^"| 
, VU , LA=address , A=address t , SP=nuraber ] L 



. BNDRY= f DBLWD ) 

Ipage j 



\ PAGE /J, 



i Note ; Only those operand combinations indicated above are valid- 

L . 



(element) written as shown; specifies a request for a single area 
of virtual storage from the subpool indicated by the SP number, 
having a length indicated by the LV operand. The address of the 
allocated virtual storage area is returned at the address indicated 
in the A operand. 

(list) written as shown; specifies a request for one or more areas 
of virtual storage from the subpool indicated by the SP number. 
The length of each virtual storage area is indicated by the values 
in a list beginning at the address specified in the LA operand. 
The address of each of the virtual storage areas is returned in a 
list beginning at the address specified in the A opereuid. No vir- 
tual storage is allocated unless all of the requests in the list 
can be satisfied. 



(register) written as shown; specifies a request for, a single area 
of viirtual storage to be allocated from the indicated subpool, and 
to have a length indicated by the LV operand. The address of the 
allocated virtual storage area is returned in register 1. If R is 
designated, the requests are unconditional; a request for more vir- 
tual storage than is available results in abnormal termination of 
the task. 



[ ] indicates optional name or operand; select one from vertical stack 
within { } ; indicates an assumed value. 
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V ^ 
(variable) written as shovm; specifies a request for a single area 
of virtual storage to be allocated from the subpool indicated by 
the SP number, and to have a length to be between two values at the 
address specified in the LA operand. The address and actual length 
of the allocated virtual storage area are returned by the control 
program at the address indicated in the A operand. 

C 

(conditional) written as shown; specifies that the request is con- 
ditional and that the task is not to be abnormally terminated if 
more virtual storage is requested than is available. If the requ- 
est is staisfied, register 15 contains a return code of 0; if not 
satisified, the return code is 4. 

U 

(unconditional) written as shown; specifies that the request is 
xinconditional. An unconditional request for more virtual storage 
than is available will result in abnormal termination of the requ- 
esting task. 

LV= 

is the length, in bytes, of the requested virtual storage. The 
number should be a multiple of 8; if it is not, the control program 
uses the next higher multiple of 8. If R is specified, LV=(0) may 
be coded; the low-ordeir three bytes of register 0 must contain the 
length, and the high-order byte must contain the subpool number. 

LA- 

is the virtual storage address of consecutive fullwords starting on 
a fullword boundary. Each fullword must contain the required 
length in the low-order three bytes, with the high-order byte set 
to 0. The lengths should be multiples of 8; if they are not, the 
control program uses the next higher multiple of 8. If V was 
coded, two words are required. The first word contains the minimum 
length required, the second word contains the maximum length. If L 
was coded, one word is required for each virtual storage area 
requested; the high-order bit is the last word must be set to 1 to 
indicate the end of the list. The list must not overlap the virtu- 
al storage area specified in the A operand. 

A= 

is the virtual storage address of consecutive fullwords, starting 
on a fullword boundary. The control program places the address of 
the virtual storage area allocated in the low-order three bytes. 
If E was coded, one word is required. If L was coded, one word is 
required for each entry in the LA ,list. If V was coded, two words 
are required. The first word contains the address of the virtual 
storage area, and the second word contains the length actually 
allocated. The list must not overlap the virtual storage area spe- 
cified in the LA operand. 

SP= 

is the number of the subpool from which the virtual storage area is 
to be allocated. The number must be between 0 and 127. If the 
operand is omitted, subpool 0 is specified. 

BNDRY= 

is the type of alignment required for the start of the requested 
area. DBLWD indicates a doubleword boundary; PAGE indicates align- 
ment with the start of a virtual page (2K boundary). If BNDRY= is 
omitted, DBLWD is assumed. BNDRY= is not valid for R-type (regist- 
er) GETMAINs. 
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After execution of the GETMAIN requests, the return code in register 
15 is as follows: 

Hexadecimal 

Code Meaning 
00 The virtual storage requested was allocated. 

04 No vritual storage was allocated (conditional form only). 

Note: A request for zero bytes or an unconditional request for more 
virtual storage than is available results in abnormal termination of the 
job step. 



Chapter 10: Descriptions of the Macro Instructions 119 



GETMAIN - L Form 



GETMAIN — List Form 

Use the list form of the GET^4AIN macro instruction to construct a 
control program parameter list. The list and execute forms of GETMAIN 
cannot be used with the R- type (register) of the macro instruction. 

The description of the standard forir. of GETMAIN explains the function 
of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The operand combinations in 
the shaded area of the format description may only be used in a VS2 sys- 
tem. The format description below indicates the optional and required 
operands in the list form only. 

J. J. _ _ ^ ^ 

tEC] C,LV=number] 

(symbol] j GETMAIN j \ [EUl[,LV=n umber] / t ,A=address] l,SP=number] | 

Clio 3 t«Xiftsaddress3 
tVC] [,LA= address] 
[VU] (,LA=address] 

j [ . BNDRY= ( DBLWD \ ] , MF=L ( 
I I PAGE i I 
j._ i __x ^ 

I Note ; Only those operand combinations indicated above are valid. | 

L- . . . . .— J 

symbol 

is any symbol valid in the assembler language- 
address 

is any address that may be written in an A-type address constant, 
number 

is any absolute expression valid in the assembler language. 

MF=L 

indicates the list form of the GETMAIN macro instruction. 



I ] indicates optional name or operand; select one from vertical stack 
within { >; indicates an assumed value. 



3-20 



GETMAIN - E Form 



GETMAIN — Execute Form 

A remote control program parameter list is used in, and can be modi- 
fied by, the execute form of the GETMAIN macro instruction. The parame- 
ter list can be generated by the list form of either a GETMAIN or a 
FREEMAIN. The list and execute forms of GETMAIN cannot be used with the 
R-type (register) of the macro instruction. 

The description of the standard form of GETMAIN explains the function 
of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The operand coinbinations in 
the shaded area of the format description may only be used in a VS2 sys- 
tem. The format description below indicates the optional and required 
operands in the execute form only. 



GETMAIN 




[EC] t,LV=number3 
CEUl [,LV=number] / [ , A=address] CSP^number] 



tVC] [,LA=addressl 
[VO] (,LA=address] 

[.BNDRY=< DBLWD \3 
\ PAGE) 

,MF= (E,( control program list address \) 

\ (1) / 
I X X 1 

I Note ; Only those operand combinations indicated above are valid. | 



symbol 

is any symbol valid in the assembler language, 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12 » previously loaded with the indi- 
cated address. You may designate the register symbolically or with 
an absolute expression; always code it within parentheses. 

number 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. The register may be designated symbolically 
or with an absolute expression, and is always coded within 
parentheses. 

MF= (E, /control program list address H 
\ (1) f 

indicates the execute form of the macro instruction psing a remote 
control program parameter list. The address of the control program 
parameter list can be coded as described under "address," or can be 
loaded into register 1, in which case MF-(E,(1)) should be coded. 



t ] indicates optional name or operand; select one from vertical stack 
within C }j indicates an assumed value. 
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GTRACE 



GTRACE — Record Trace Data 

Use the GTRACE macro instruction to record data in a trace data set, 
using GTF (generalized trace facility). This data set may later become 
input to an editing function provided by HMDPRDMP service aid. An 
optional parameter allows you to specify a specific format routine (user 
written if desired) to process the record after the trace output is 
edited. 

To use GTRACE, GTF must be active and ready to accept data from the 
problem program. Also, the trace data set must be identified in the GTF 
job control statements. 

The standard form of the GTRACE macro instruction is written as shown 
below. Information about the list and execute forms follows this 
description. 

r ' T r- 1 

I [symbol] | GTRACE | DATA=addr ess, LNG=number ,ID=n umber | 

II I [,FIO=number] | 

L ± J. J 

DATA= 

is the virtual storage address of the data to be recorded. 

LNG= 

is the number of bytes of data to be recorded. Specify any number 
from 1 to 256. 

ID= 

is the identifier to be associated with the record. ID values are 
assigned as follows: 

0-1023 user events 
1024-1095 reserved 

FID= 

is the format identifier indicating the format routine used to pro- 
cess the record when the trace output is edited by HMDPRDMP. You 
may provide your own routine to handle this data. Format identifi- 
er values are; 

0 hexadecimal dump of entry 
1-80 user format identifiers 
81-255 reserved 

If the FID parameter is omitted,, 0 is assumed. 

The format identifier must be converted to hexadecimal. If it is not 
0 , it is appended to the name HMDUSR to form the name of the format rou- 
tine used by HMDPRDMP to process the record. For example, FID=50 con- 
verts to X*32*. Module HMDUSR32 is used by HMDPRDMP to process the 
trace record. 

Formatting routines must be in SYSl.LINKLIB or in a private library 
defined in a JOBLIB or STEPLIB DD statement for HMDPRDMP. 

A return code is placed in register 15 when control is returned to 
the problem program. 



I 1 indicates optional name or operand. 
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GTRACE 

Hexadecimal 



Code Explanation 

00 Successful completion. 

04 GTF not active or not accepting probleir. progreun entries. 

08 Length specified in LNG parameter is greater than 256. 

OC Invalid data address. 

10 FID value is greater than 255. 

14 Value of IQ parameter is greater than 1023. 

18 Buffers are full; record was not placed in buffer. 

IC Invalid address of parameter list. 

20 Data paged-out, cannot be gathered. 
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GTRAce - h Form 

■ ■ ■ ■ , / 

■ . • , . ■ ■ ■ ; [ 

GTRACE — List Form 

The list form of the GTRACE macro instruction constructs a control 
program parameter list. Use the list form of GTRACE to pass address 
parameters in a parameter list to the control program. This parameter 
list can then be referred to by issuing the execute form of GTRACE. 

The description of the standard form of GTRACE explains the function 
of each operand. The format description below indicates the optional 
and required operands for the list form only. 

r- — ^- T-*^-- ' — —1 — • ■ ■ — I . 

j (symbol] \ GTRACE | ( DAT A=address] CLNG:^ length] j 
11 j £,FIO==number],MF=L | 



address 

is any address value that can be expressed as an A-type address 
constant. 

length 

is any number from 1 to 256. 
number 

is any number from 0 to 80. 

MF=L 

indicates the list form of the macro instruction. 
Note ; The ID parameter is not valid in the list form of GTRACE. 



( ] indicates optional name or operand. 
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GTRACE - E Form 



GTRACE — Execute Form 

The execute form of the GTRACE macro instruction uses the remote con- 
trol program parameter list created by the list form of GTRACE. The 
description of the standard form explains the function of each operand. 
The format description below indicates the operands for the execute form 
only. 

r T T ; ^ 

I (symbol] j GTRACE | ID=value,MF= (E, /parameter list address i) | 
III I (1-12) I 1 
i 1 I (,OATA=address] (,LN&=length] i 
I I j (,FID-number] | 
L X X . : I 

value 

is any number from 0 to 1023. 

MF=(E, (parameter list address H 
I (1-12) f 

indicates the execute form of the macro instruction using a remote 
control program parameter list. If you load the address of the 
list into register 1, code MF=(E, (1)). If the address is not 
loaded into register 1, code it as any address that is valid in an 
RX-type instruction, or as a register 2-12, previously loaded with 
the address. You may designate the register symbolically or with 
an absolute expression. Always code the register value in 
parentheses. 

address 

is any address that can be expressed as an A-type address constant, 
length 

is any number from 1 to 256. 
number 

is any number from 0 to 80. 



[ 1 indicates optional name or operand; select one from vertical stack 
within { }. 
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IDENTIFY 

IDENTIFY — Add an Entry Point 

Use the IDENTIFY inacro instruction to add an entry point to a copy of 
a load module currently in virtual storage. The copy must be one of the 
following: 

• A copy that satisfied the requirements of a LOAD macro instruction 
issued during the execution of any task within the partition/ region. 

• The last load module given control # if control was passed to the 
load module using a LINK, ATTACH, or XCTL macro instruction. 

• The first load module of any task, if it is still in control. 

The IDENTIFY macro instruction may not be issued by an asynchronous 
exit routine. The routine associated with the entry point must be 
reenterable. 

In VSl, IDENTIFY may not be issued by a routine entered at an added 
entry point. The added entry point can be used only in an ATTACH macro 
instruction. 

The IDENTliPY macro instruction is written as follows : 

r T r- • ' — • 1 

I [symbol] I IDENTIFY I (EP=symbol »,ENTRY=entry point address j 

j I I \EPLOC=address of name/ | 

.1 J . _. — . J 

EP= 

is the name of the entry point. The name does not have to corre- 
spond to any name or symbol in the load module, and must not corre- 
spond to any name, alias, or added entry point for a load module in 
the resident reenterable module area, LPAQ area, or the job pack 
area of the job step. 

EPLOC= 

is the address of the entry point name described under EP. Pad the 
name with blanks to eight bytes, if necessary. 

ENTRY= 

is the virtual storage address of the entry point being added. 

When control is returned, register 15 contains one of the following 
return codes : 

Hexadecimal 

Code Meaning 
00 Successful completion. 

04 Entry point name and address already exist. 

08 Entry point name duplicates the name of a load module cur- 

rently in virtual storage; entry point was not added. 

OC Entry point address is not within an eligible load module; 

entry point was not added. 

10 Issued by an asynchronous exit routine; the entry point 

was not added. 

in An IDENTIFY macro instruction was previously issued using 

the same entry point name but a different address; this 
request was ignored. 



t ] indicates optional name; select one from vertical stack within { >. 
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LINK — Pass Control to a Program in Another Load Module 

Use the LINK macro instruction to pass control to a specified entry 
point in another load module; the entry point name must be a member name 
or an alias in a directory of a partitioned data set. The load module 
containing the program is brought into virtual storage if a useable copy 
is not available. (Refer to the Services section of this publication, 
for a discussion of the use of an existing copy of the load module.) 

The linkage relationship established is the same as that created by a 
BAL instruction; control is returned to the instruction following the 
LINK macro instruction after execution of the called program. The prob- 
lem program optionally can provide a parameter list to be passed to the 
called program. If the called program terminates abnormally, or if the 
specified entry point cannot be located, the task is abnormally 
terminated. 

The standard form of the LINK macro instruction is written as sho%m 
below. Information about the list and execute forms follows this 
description. 

r T T 1 

I (symbol] | LINK | (£P=symbol \ [,DCB^cb address] | 

I I 1 < EPLOC=address of name > | 

I I I (DE=address of list entry) | 

I 1 1 (, PARAM= (addresses) 1 t,VL=l] [,ID=number] | 

L X X J 

EP= 

is the entry point name in the program to be given control. 
EPLOC= 

is the address of the entry point name described above. Pad the 
name with blanks to eight bytes, if necessary. 

DE= 

is the address of the name field of a 58-byte (60 bytes in VS2) 
list entry for the entry point name. The list entry is constructed 
using the BLDL macro instruction using a length specification of 58 
or 60 bytes. The DCB operand must indicate the same data control 
block used in BLDL. 

DGB= 

is the address of the data control block for the partitioned data 
set containing the entry point name described above. 

If the DCB operand is omitted or if DCB=0 is specified when the 
LINK macro instruction is issued by the job step task , the data 
sets referred to by either the STEPLIB or JOBLIB DD statement are 
first searched for the entry point name. If the entry point name 
is not found, the link library is searched. 

If the DCB operand is omitted or if DCB=0 is specified when the 
LINK macro instruction is issued by a subtask , the data sets asso- 
ciated with one or more data control blocks referred to by previous 
ATTACH macro instructions in the subtasking chain are first 
searched for the entry point name. If the entry point name is not 
found, the search is continued as if LINK had been issued by the 
job step task. 



[ ] indicates optional name or operand; select one from vertical stack 
within { } . ■ 
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LINK 



is one or more address parameters, separated by commas, to be 
passed to the called program. Each address is expanded inline to a 
fullword on a fullword boundary, in the order designated. Register 
1 contains the address of the first parameter when the program is 
given control. (If this operand is omitted, register 1 is not 
altered.) 

VL=1 

is written as sho%m. It can be designated only if PARAM is desig- 
nated, and should be used only if the called program can be passed 
a variable number of parameters. VIr=l causes the high-border bit of 
the last address parameter to be set to 1; the bit can be checked 
to find the end of the list. 

ID= 

specifies a decimal integer with a maximum value of 2^«-l. The 
last fullword of the macro expansion is a NOP instruction contain- 
ing the ID value in bytes 3 and 4. This operand is useful for 
debugging purposes only. 
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LINK - L Form 



LINK — List Form 

Two parameter lists are used in a LINK macro instruction: a control 
program parameter list and an optional problem program parameter list. 
Only the control program parameter list can be constructed in the list 
form of LINK. Address parameters to be passed in a parameter list to 
the problem program can be provided using the list form of CALL. This 
parameter list can be referred to in the execute form of LINK. 

The description of the standard form of LINK explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of 
the pair of list and execute forms. The format description below indi- 
cates the operands in the list form only. 

r T T 1 

I [symbol] | LINK j ( EP=symbol U,DCB=dcb address] | 

I I I ^ EPLOC=address of name > j 

j 1 I ( 0£=address of list entry) i 

I I I .SF=L I 

L X J J 

symbol 

is any symbol valid in the assembler language. 

address 

is any address that may be written in an A-type address constant. 

SF=L 

indicates the list form of the LINK macro instruction. 



t ] indicates optional name or operands; select one or none from verti- 
cal stack within ( ] . 
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LINK - E Form 



LINK — Execute Form 



Two parameter lists are used in a LINK macro instruction: a control 
progrcim parameter list and an optional problem program parcimeter list. 
Either or both of these lists can be remote and can be referred to and 
modified by the execute form of LINK. If only one of the parameter 
lists is remote, operands that require use of the other parameter list 
cause that list to be constructed inline as part of the macro expansion. 

The description of the standard form of LINK explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of a 
pair of list and execute forms. The format description below indicates 
the operands in the execute form only. 



I 

i [symbol] | LINK 



Vl,DCB=dcb address] 



!EP=symbol 
EPLOC=address of name / 
DE=address of list entry; 
[,PARAM= (addresses)] (,VL=1] [,ID=number] 
,MF=(E,) problem program list addressi)' 

\ (1) / 

, SF=(E, ( control program list address 

t (15) 
,MF=(E,) address |) ,SF=(E, ^ address p 

\ (1) / \ (15) ; 

L : X i . 1 



r 



J 



symbol 

is any symbol valid in the assembler language - 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. The register may be designated symbolically or with 
an absolute expression; always code it within parentheses. 

number 

is any absolute expression that is valid in the assembler language. 

MF=(E,/ problem program list address)) 

\ (1) / 

indicates the execute form of the macro instruction using a remote 

problem program parameter list . Any control program parameters 
specified are provided in a control program parameter list expanded 
inline. The address of the problem program parameter list can be 
coded as described under "address," or can be loaded into register 
1, in which case code MF=(E, (1)). If you code the PARAM operand, 
the addresses are placed in contiguous fullwords at the user pro- 
blem program list address. 

SF=(E, (control program list address)) 
\ (15) I 

indicates the execute form of the macro instruction using a remote 
control program parameter list . Any problem program parameters 
specified are provided in a problem program parameter list expanded 
inline. The address of the control program parameter list can be 
coded as described under "address," or can be loaded into register 
15, in which case code SF=(E, (15)). 



[ ] indicates optional name or operand; select one from vertical staclc 
within { }; select one or none from vertical stack within [ ]. 
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LINK - E Forn 



MF=(E, (address \) ,SF=(E, (address \) 
\ (1) / \ (15)/ 

indicates the execute form of the macro instruction using both a 
remote problem program parameter list and a remote control program 
parameter list. The addresses of the parameter lists are coded or 
loaded into registers 1 and 15, as explained above. 



Select one from vertical stack within { }. 
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LOAD 



LOAD — Bring a Load Module Into Virtual Storage 

Use the LOAD macro instruction to bring the load module containing 
the specified entry point into virtual storage, if a usable copy is not 
available in virtual storage. (Refer to "Using an Existing copy" for a 
discussion of the use of an existing copy of the load module.) The 
responsibility count for the load module is increased by one. On out- 
put, the high-order byte of register 1 contains the authorization code 
of the loaded module and the low three bytes contain the module^ s 
length. Control is no t passed to the load module; instead, the virtual 
storage address of the designated entry point is returned in register 0. 
The load module remains in virtual storage until the responsibility 
count is reduced to 0 through task terminations or until the effects of 
all outstanding LOAD requests for the module have been canceled (using 
the DELETE macro instruction) , and there is no other requirement for the 
module. 

The entry point name in the load module must be a member name or an 
alias in a directory of a partitioned data set. If the specified entry 
point cannot be located, the task is abnormally terminated. 



r T r 1 

I [symbol! | LOAD | (EP=symbol U,DCB=dcb address] j 

I 11 \EPLOC=address of name [ | 

1 I I (DE=address of list entry) | 

L X i.: J 



EP= 

is the entry point name in the load module to be brought into vir- 
tual storage. Pad the name with blanks to eight bytes, if 
necessairy . 

EPLOC= 

is the virtual storage address of the entry point name described 
above. Pad the name with blanks to eight bytes, if necessary. 

DE= 

is the address of the name field of a 5 8-byte list entry for the 
entry point name instruction. The list entry is constructed by a 
BLDL macro, using a length specification of 58 bytes. The DCB 
operand must indicate the same data control block used in the BLDL 
macro. 

DCB= 

is the address of the data control block for the partitioned data 
set containing the entry point name described above. 

If the DCB operand is omitted or if DCB=0 is specified when LOAD is 
issued by the -job step task , the data sets referred to by either 
the STEPLIB or JOBLIB DD statement are first searched for the entry 
point name. If the entry point name is not found, the link library 
is searched. 



If the DCB= operand is omitted or if DCB=0 is specified when LOAD 
is issued by a subtask , the data sets associated with one or more 
data control blocks referred to by previous ATTACH macros in the 
subtasking chain are first searched for the entry point name. If 
the entry point name is not found, the search is continued as if 
LOAD had been issued by the job step task. 



[ ] indicates optional name operand; select one from vertical stack 
within { > . 
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PGRLSE — Release Virtual Storage Contents 



PGRLSE 



The PGRLSE macro instruction makes all complete pages of real and 
external page storage wholly associated with the area of virtual address 
space specified available. The address space remains intact but its 
contents are forfeited. Use PGRLSE when a large area (one or more com- 
plete pages) of virtual storage within your program no longer has 
meaningful or significant contents. 

When you issue a PGRLSE macro instruction, all complete pages of vir- 
tual storage between the low and high addresses specified are released. 
You can help reduce system overhead by releasing virtual storage when 
you no longer need it. 

The standard form of the PGRLSE macro instruction is written as fol- 
lows. Information about the list and execute forms follows this 
description. 



r T T ^ 1 

I [symbol] I PGRLSE | LA=iaddrl \,HA=jaddr2 \ \ 
I i i l(regl)/ \ (reg2)/ | 

L X X J 



LA= 

is the low address of the area to be released. Addrl specifies the 
low address; regl indicates a general register containing the 
address. (1) may not be specified. 

HA= 

is the high address + 1 of the area to be released (low address + 
length of area) . Addr2 specifies the high address + 1; reg2 indi- 
cates a general register containing the address. HA=(0) may not be 
specified. 

Upon completion of PGRLSE, register 15 is set as follows: 



Hexadecimal 

Code jyieaning 
00 Successful completion. 

04 Execution failed. The area specified, or a portion of 

it, is protected from the requesting program. Any 
valid portion of the area preceding the protected area 
is released. 



( J indicates optional name; select one from vertical stack within { }. 
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PGRLSE — List Form 

Use the list form of the PGRLSE macro instruction to construct a con- 
trol program parameter list. 

The description of the standard form of PGRLSE explains the function 
of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The following format 
description indicates the operands in the list form only- If LA or HA 
is coded, addresses must be specified; register notation cannot be used. 

r T r • 1 

I [symbol] | PGRLSE j MF=LC ,LA=addrl] ( ,HA=addr2] | 

L : X ± ^_ . : J 



symbol 

is any symbol valid in the assembler language. 

J4F=L 

indicates the list foirm of the PGRLSE macro instruction. 

addr 

is any address that may be written in an A-type address constant. 



[ 1 indicates optional name or operands. 
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PGRLSE - E Form 



PGRLSE — Execute Form 

A remote control program parameter list is referred to, and can be 
modified by, the execute form of the PGRLSE macro instruction. 

The description of the standard form of PGRLSE explains the function 
of each operand. The description of the standard form also indicates 
which operands are always optional and which are required in at least 
one of the pair of list and execute forms. The format description below 
indicates the operands for the execute form only. 

An execution error is indicated if the list address is outside of 
your partition, or if it is of a different storage protection key. 

[ [symbol] | PGRLSE J MF=7e, (listaddr\\T,LA=/addrl r,HA=/addr2 Y] ] 
I I I \ I Creg3) j/L \(regl)/JL \(reg2)/J | 
L X X : ■ . J 



symbol 

is any symbol valid in assembler language. 

MF^ {£ , ( listaddr \ \ 
\ \ (reg3) // 

indicates the execute form of the macro instruction using a remote 
control program parameter list- The address can be any address 
that is valid in an RX-type instruction. Reg3 indicates a register 
(2-12) containing the address. Optimum performance occurs if a 
register is specified. 

addr 

is any address that may be written as an A-type address constant. 
Reg indicates one of the general registers previously loaded with 
the indicated address. The register may be designated symbolically 
or with an absolute expression, and is always coded within paren- 
theses. Neither LA=(1) nor HA=(0) may be specified. 



I J indicates optional name or operand; select one from vertical stack 
within { } . 
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POST — Signal Event Completion 

Use the POST macro instruction to have the specified ECB (event con- 
trol block) set to indicate the occurrence of an event- If this event 
satisfies the requirements of an outstanding WAIT macro instruction, the 
waiting task is taken out of the wait state and dispatched according to 
its priority. The bits in the ECB are set as follows: 

Bit 0 of the specified ECB is. set to 0 (wait bit). 

Bit 1 is set to 1 (complete bit). 

Bits 8 through 31 are set to the specified completion code. 

Figure 58 shows the format of the event control block and its asso- 
ciated completioii codes. 

The POST macro is written as follows: 

r T T ■ ■ 1 

I (symbol] | POST | ecb address completion code] | 
I X JL _J 

ecb address 

is the address of an event control block representing the event, 
completion code 

is a value between 0 and 2^*-l. If the completion code is not 
designated, 0 is assumed. 



[ ] indicates optional name or operand. 
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RETURN — Return Control 

The RETURN macro instruction restores control to the calling program 
and signals normal termination of the called program. The return of 
control is always made by executing a branch instruction using the 
address in register lU. The RETURN macro instruction can restore a 
designated range of registers, provide a return code in register 15, and 
flag the save area used by the called program. 

If registers are to be restored, or if an indicator is to be placed 
into the save area, register 13 must contain the address of the save 
area, which must have the standard format. 

The RETURN macro instruction is written as follows: 

r T T 1 

I [symbol] j RETURN j I ( regl [ , reg21 ) ] [ ,T] r,RC=nurober1 | 
I I I [,RC=(15) J I 
L X X , . J 



regl,reg2 

is the range of registers to be restored from the save area pointed 
to by the address in regislier 13- The registers should be desig- 
nated to causfe the loading of registers lU, 15, 0 through 12 when 
used in an LM instructioiiV If you do not specify reg2, only the 
register designated by the regl operand is loaded. If you omit the 
operand, the cdhtents of the registers are not altered. Do not 
code regl or reg2 when returning control from a program interrup- 
tion exit routine. 

T 

causes the control program to flag the save area used by the called 
program. A byte containing all l*s is placed in the high-order 
byte of word 4 of the save area after the registers have been 
loaded. It desiginatess that a called program has executed a return 
to its caller. Do not ^lecxty this operand when returning control 
from an exit routine. 

RC= 

is the return code to be passed to the calling program. The return 
code should have a maximum yailue of 4095; it is placed right- 
adjusted in register 15 before return is made. If you code RC=( 
15) , it indicates that the return code has been previously loaded 
into register 15; in this case the contents of register 15 are not 
altered or restored from the save area. (If you omit this operand 
the contents of register 151 aire determined by the ^^r^ 
. operands . ) ' ^■ 



I I indicates optional name or operand; select one or none from vertical 
stack within t ] . 
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SAVE — Save Register Contents 

The SAVE macro instruction stores the contents of the specified reg- 
isters in the save area at the address contained in register 13. If you 
wish, you may specify an entry point identifier. Write the SAVE macro 
instruction only at the entry point of a program because the code 
resulting frOm the macro expansion requires that register 15 contain the 
address of the SAVE macro prior to its execution. Do not use the SAVE 
macro instruction in a program interruption exit routine. 

The SAVE macro is written as follows : 

r — - — " "T" r ■ ■ — -1 

I [symbol] j SAVE | (regl[,reg2]), tT] [, identifier name! | 

L . J. X . _. J . ■ ■ 

regl , reg2 

is the range of registers to be stored in the save area at the 
address contained in register 13. The registers should be designa- 
ted so they are stored in the order 14, 15, 0 through 12 when used 
directly in an STM instruction. Do not specify register 13. The 
registers are stored in words 4 through 18 of the save area- If 
only one register is designated, only that register is saved. 

T 

specifies that registers IH and 15 are to be stored in words H and 
5, respectively, of the save area. If you specify both T and reg2, 
and if regl is any of registers 14, 15, 0, 1, or 2, all of regis- 
ters lU through the reg2 value are saved. The T operand permits 
you to save two noncontiguous sets of registers. 

identifier name 

is an identifier to be associated with the SAVE macro instruction. 
The name may be up to 70 characters and may be a complex neune. If 
an asterisk is coded, the identifier is the symbol associated with 
the SAVE macro instruction, or, if the name field is blank, the 
control section name is used. The identifier aids in locating a 
program's save area in a dump. If the CSECT instruction name field 
is blank, the operand is ignored. Whenever a symbol or an asterisk 
is coded, the following macro expansion occurs: 

• A count byte, containing the number of characters in the identi- 
fier name, is assembled four bytes following the address con- 
tained in register 15 . 

• The character string containing the identifier name is assembled, 
starting at five bytes following the address contained in regis- 
ter 15. 

• An instruction to branch around the count and identifier fields 
is assembled. 



( ] indicates optional name or operand. 
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SEGWT — Load Overlay ^iegn ie nt and Wait 

The SEGWT macro instruction causes the control program to load the 
specified segment and any segments in its path that are not part of a 
path already in virtual storage. Control is not passed to the specified 
segment; control is not returned to the segment issuing the SEGWT macro 
instruction until the requested segment is loaded. Refer to the publi- 
cation Linkage Editor and Loader , for details cn overlay operations. 
The SEGWT macro instruction cannot be used in an asynchronous exit 
routine. 

The SEGWT macro instruction is written as follows: 

r T r 1 

I [symbol] | SEGWT | external segment name | 

L X X J 

external segment name 

is the name of a control section or entry point in the reguired 
segment. An exclusive reference is not allowed. The name does not 
have to be identified by an EXTRN statement. 



(] indicates optional name. 
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SNAP— Dump Virtual Storage and Continue 

The SNAP macro instruction is used to obtain a dump of some or all of 
the storage assigned to the current job step. Some or all of the con- 
trol program fields can also be dumped. The format of the dump is simi- 
lar to the abnormal termination dump shown in the VSl and VS2 Dehugqinq 
Guides . ■ 

You must provide a data control block and issue an OPEN macro 
instruction for the data set before aiay SNAP macro instructions are 
issued . The PCB macro instruction must contain the f oliowing operands : 

DS0RG=PS,RECF«=VBA,{4ACRF= (W) ,BLKSIZE=nnn,(LR£CL=125 
and DDNAME-any name but SYSABEND or SYSUDUMP 

BLKSIZE must be 882 in VSl, and either 882 or 1632 in VS2. A SNAP data 
set that is opened in a problem program that will be processed by the 
system loader should be closed by the proisibm program. 

The data set containing the dump can reside on any device supported 
by BSAM (basic sequential access method). The dump is placed in the 
data set described by the DD statement the user provides. If a printer 
is selected, the dump is printed immediately; if a direct access or tape 
device is designated, a separate job must be scheduled to obtain a list- 
ing of the dump. 

Sufficient unused storage must be available in the area assigned to 
the job step to hold the control program dump routine and, if not 
already in storage, the BSAM data management routines . 

The standard form of the SNAP macro is written as shown below. 
Information about the list and execute forms follows this description. 

r —T T — ■ • — — ■ : ■ 1 

I [symbol] I SNAP I DCB=dcb address [,TCB=addr ess] | 
I I I ( ,ID=niirober] £ ,SDATA= (code f or control program blocks)] | 

I I I [ , PDATA= ( code f or problem program areas)] | 



I 



j r , STGRAGE= ( sta rti ng address , ending address ,,..)! 
I L,LIST=address of list J 



DCB= 

is the address of the data control block for the data set that is 
to contain the dump. This DGB must be open before SNAP is 
executed. If the DCB is omitted or specified in register format, 
the DOB address will default to 0^ 

TCB= 

specifies the address of a fullword on a fullword boundary contain- 
ing the address of the task control block for a task of the current 
job step. If omitted, or if the fullword contains 0, the dump is 
for the active task. If a register is designated, the register can 
contain 0 to indicate the active task, or can contain the address 
of a task control block. 



[ ] indicates optional name or bperand; select one or none from vertical 
stack within t 1; indicates that more than one pair of starting and 

ending addresses can be specified. 
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ID= 

is a number between 1 and 127. The number is printed in the iden- 
tification heading associated with the dump. If specified in reg- 
ister format, the ID will default to 0. 



SUATA= 

one to four of the following sets of characters, written in any 
order and separated by commas. The characters are used to request 
the associated control program information: 



Code Fields Dumped 

ALL All of the following fields. 

NUC All of tho control program nucleus except the trace 

table. 

TRT Trace Table. Ignored if GTF is active and was started 

with the S parameter specified (formatting of the GTF 
trace buffers suppressed). 

CB Task control block (TCB) , active request blocks (RBs), 

job pack area control queue (JPACQ) and control blocks. 

Q Ignored. 



one to five of the following sets of characters, written in any 
order and separated by commas. Use these characters to request the 
following problem program information: 



Code Fields Dumped 

ALL All of the following fields. 

PSW Program status word when the SNAP macro instruction was 

issued. 

REGS Contents of the general registers when the SNAP macro 

instruction was issued. 
SA or SAH SA - provides linkage information and a back trace 

through save areas. SA is selected if ALL is coded. 

SAH - only linkage information. 
JPA or LPA JPA - all virtual storage assigned to the job step, 
or ALLPA LPA - contents of the resident reenterable load module 

area. 

ALLPA - contents of both pack areas. ALLPA is selected 
if ALL is coded. 
SPLS All virtual storage assigned to job step. 



STORAGE= 

is one or more pairs of starting and ending addresses; the areas 
between the starting and ending addresses are dumped one f ullword 
at a time. If the starting and ending addresses are not fullword 
multiples, the addresses are rounded down (starting) and up (end- 
ing) to a fullword. 

The area to be dumped must be in your program's partition/region. 
If the addresses are not within the partition/region, a condition 
code of 00 is returned but the storage area is not dumped. 

LIST= 

the address of a list of starting and ending addresses of areas to 
be dumped. The addresses in the list are treated in the same man- 
ner as the addresses described for the STORAGE operand. The list 
must begin on a fullword boundary; each address in the list occu- 
pies one fullword. The high-order byte of each word containing the 
starting address of an area to be dumped must contain zeros or that 
pair will be skipped. The high-order bit (bit 0) of the fullword 
containing the last ending address in the list roust be set to 1. 
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Control is rieturned to the instruction following the SNAP macro 

in3;truction. When control is returnedv. register 15 contains one of the 
following return codes: 

Hexade^iijiieil 

Code ! Meaning 
00 Successf ul Gompifiti^orii.. 

04 Data control block v#£i6 not Open. 



08 



sy<|dpOKl£^: , is^ij unavailable. Or dun.p 

•^lleiit' i^y^' tasi^ mi,^.. at- s&eg' .as5.'a^ subtask.... 



06 Data control block type was ncjt CQrreet (DSORG, REGFM, 

MAGRF, BLKSIZE, or LRBGL field) . 



1U2 
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SNAP — List Form 

Use the list form of the SNAP macro to construct a control program 
parameter list. You can specify any number of storage addresses using 
the STORAGE operand. Therefore, the number of starting and ending 
address pairs in the list form of SNAP must be equal to the maximum 
number of addresses specified in any execute form of the macro, or a 
DS instruction must immediately follow the list form to allow for the 
maximum number of addresses . 

The description of the standard f orir. of the SNAP nsacro provides the 
explanation of the function of each operand. The description of the 
standard form also indicates which operands are always optional and 
which are required in at least one of the pair of list and execute 
forms. The format description below indicates the optional and required 
operands in the list form only. 

r T- T 1 

I (symbol] |SNAP| [DCB=address] (,ID=n umber] [, SDATA= (code) ][ ,PDATA= (code) 1 | 
I I I r,STORAGE= (address, address, ... )"| ,MF=L | 

I j I L, LIST=address J | 

L X X J 

symbol 

is any symbol valid in the assembler language. 

address 

is any address that may be written in an A-type address constant. 
If the address is omitted, the default value is 0. 

code 

is written as indicated in the description of the standard form of 
the macro instruction. 

number 

is any absolute expression valid in the assembler language. 

MF=L 

indicates the list form of the SNAP macro instruction. 



t ] indicates optional name or operand; select one or none from vertical 
stack within I ] ; , . - - indicates that more than one pair of starting 
and ending addresses can be specified. 
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SN3^ Execute Form 

A remote control program parameter list is referred to and can be 
modified by the execute form of the SbJAP macro instruction. 

If you code only the DCB, ID, Mf; , or TCB operands in the execute form 
of the macro instruction, the bit settings in the parameter list corres- 
ponding to the SDATA, FDATA# LIST , and^ STORAGE operands are not changed . 
However, if you code one or more of thi§ spATA, PDATA, LIST operands, the 
bit settings from the pjcevious re<|uest: are reset to and only the 

areas requested in the current macro instruction are dumped. 

The . desciriptidn of thie standard fornr of SNAP explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of 
the pair of list and execute forms. The format description below indi- 
cates the optional and required operands in the execute form only. 

r—- — • T— T — ^ ■ — — ^— ' ^ — --■ '— -— — 1 

j [symbol] j SNAP | [DCB=address] ( ,TCB=/; S* H I, ID=numberl | 

I I I . (address/ | 

I I I [,PDATA=code][,SDATA=^code] 1 

I I I r, STORAGES (address, address,. . .)] | 

I j I L,xiST=address J I 

I I I ,MF=(E, /control program list address)) | 

I I I \ (1) r I 

L . ; X X ._ — -J 

symbol 

is any symbol valid in the assembler language, 
address 

is any address that is valid in an R3trtype instruction, or one of 
general registers 2 throu«gh 12, previously loaded with the indi- 
cated address. You may designate the register symbolically or with 
an absolute expression; always code it within parentheses. If the 
address is omitted, the default value is 0. 

is used to specify the task control block of the active task, 
number 

is any absolute expression that is valid i the assembler language,! 
or one of general registers 2 through 12, previously loaded with 
the indicated value. You may designate the register symbolically 
or with an absolute expression; aliii*ays cb^^ it within parentheses. 

code 

is written as indicated in the desbription of the standard format 
of the macro instruction. 

MF= (E,/ control program list addressi) 

\ (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list. The address of the control program 
parameter list can be coded as descrited under "address , " or can be 
loaded into register 1, in which case code 



[ ] indicates optional name or operand; select one or none from vertical 

stack within [ 1; , indicates that more than one pair of starting 

and ending addresses can be specified- Select one from vertical stack 
within { > . 
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SPIE — Specify Proqrair Interruption Exit 

The SPIE macro instruction specifies the address of an interruption 
exit routine and the prograir interruption types that are to cause the 
exit routine to be given control. If the program interruption types 
specified can be masked, the corresponding program mask bit in the PSW 
(program status word) is set to 1. 

The effect of each SPIE macro instruction issued in performance of a 
task supersedes the effect of the previous SPIE issued in performance of 
the same task. The specified exit routine is given control when one of 
the specified program interruptions occurs in any program of the task. 

The SPIE macro instruction can be issued by any subtask of the task; 
the resulting environment exists for the entire subtask. 

A PICA (program interruption control area) is created as part of the 
expansion of SPIE. The PICA, shown in Figure 56, contains the exit rou- 
tine's address and a code indicating the interruption types specified in 

SPIE. 



Any program issuing a SPIE macro instruction must restore the pre- 
vious PICA before returning to the calling program. The previous PICA 
address is returned in register 1 after execution of SPIE; this address 
can be used to restore the PICA before returning control. If no SPIE 
environment exists when the SPIE macro instruction is issued, register 1 
is set to 0 when control is returned. A SPIE macro instruction with no 
operands (a canceling SPIE) creates a null SPIE environment (program 
mask set to zero, no program interrupts intercepted, and no exit rou- 
tine; however the PICA created by this SPIE is controlling the SPIE 
environment). To reestablish a previous SFIE, whether or not a cancel- 
ing SPIE has been issued, issue the execute form of SPIE, specifying the 
address of the appropriate PICA- Issuing a canceling SPIE causes the 
address of the previous PICA to be returned. 

In addition to the PICA, there is one PIE (program interrupt element) 
per task. The PIE is 32 bytes long, the first four bytes of which con- 
tain the address of the PICA. The forirat of the PIE is shown in Figure 
3U. The PIE is built when the first SPIE macro instruction is issued 
and remains in effect as long as the task is active. 



The PICA address in the PIE is the address of the PICA used in the 
last execution of a SPIE macro instruction for the task. When control 
is passed to the routine indicated in the PICA, the old PSW contains the 
interruption code in bits 16-31. These bits can be tested to determine 
the cause of the program interruption. The contents of registers lH, 
15, 0, 1, and 2 at the time of the interruption are stored by the con- 
trol program as indicated in Figure 57. 



Bytes 1 3 2 



, ,. ... — 


—A . v.— >r- 


^ ^ 


1 


1 1 1 


■ ' 1 


1 0000 

1 


1 Program | Exit Routine Address | 
1 Mask 1 1 


Interruption Mask | 

1 


1 


1 1 1 


1 



figure 56. Program interruption control area (PICA) 
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I Heserved | PIGA Address ( 

I Old Prograni j (interruption codes > ( 

I Status Word 1 

I (Resulting froir the Interrupt ion) j 

j Register 14 j 

i Register 15 1' 

|: Register 6 | 

I Register i I 

I Register 2 | 
32 1 — — J.. 

Figure 57. Prograir interruption eleBrent (Fi£) 



The standard form of the SPIE macro instruction is written as shGWn 
below. Information about the list and execute forms follows this 
description. 

I [symboll I SPIE I (interruption exit address, (interrupti | 

interruption exit address 

is the address of the exit routine to be given control when a prO'^ 
gram interruption of the type specified in the: interru^ 
operand occurs. 

interruptions 

is one or more decimal number^, sep^^ra 

type of program interruption . to bsfe hairidi^^ exit rou- 

tine. Interruption typies not- spe<: if i<^^^ handled by the control 
program. The inteirruptidn, types ca^ order as 

follows : 

• One or more single numbers, each; indicatihg the correspo 
program interruption type. 

• One or more pairs of decimal numbers, each pair indicating a 
range of corresponding interruption types. The second humber 
mu^t be higher than , the first numbers must be 
separated f rom each Mother by cpmmas; a an addi-^ 
tiohai set of .parentheses. 

For example, (4,8) indicates interruptiph types 4 and 8 ; ( (4 ,8 ) ) 
indicates interruption types 4 thrGugh 8. If a specified program 
interruption type is maskable, the correspdnding bit is set to 1. 
The interruption types are as follows: 



Number 


Interruption Type 


1 


Operation 


2 


Privileged operation 


3 


Execute 


4 


Protection 


5 


Addressing 
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Number 



6 
7 
8 

9 
10 
11 
12 
13 
14 
15 



Interruption Type (Cont'd) 

Specif ication 

Data 

Fixed-point overflow (maskable) 

Fixed-point divide 

Decimal overflow (maskable) 

Decimal divide 

Exponent overflow 

Exponent underflow (maskable) 

Significance (maskable) 

Floating-point divide 



The user-provided SPIE exit routine is executed whenever one of the 
types of specified interruptions occurs. The exit routine must be in 
virtual storage when it is required. Since the routine operates as a 
subroutine of the control program, it must return control to the control 
program. 

Input to the SPIE exit routine is as follows. 
Register 0 ; Control program information. 

Register 1 : Address of the PIE for the task that caused the inter- 
ruption (Figure 57) . 

Register 2-12 : Same as when the program interruption occurred. 

Register 13 ; Address of the save area for the main program. The 
exit routine must not use this save area. 

Register lU ; Return address to the control program. 

Register 15 ; Address of the exit routine. 

The exit routine must be in virtual storage when it is required and 
must return control to the control program using the address passed in 
register 14. The control program restores registers 14, 15, 0, 1, and 2 
from the PIE after control is returned but does not restore the contents 
of registers 3-13. 

To determine which type of interruption occurred, the exit routine 
can test bits 28-31 of the OPSW (old program status word) in the PIE. 
The routine can then take corrective action, or it ceui ignore the excep- 
tional condition. 

The exit routine can alter the contents of the registers that are to 
be returned to the interrupted program. For registers 3-13, the routine 
alters the contents of the actual registers. For registers 14, 15, 0, 
1, and 2, the routine alters the contents of the register save area in 
the PIE. This is because the control program reloads these registers 
from this save area when it returns control to the interrupted program. 

The exit routine can also alter the last four bytes of the OPSW in 
the PIE. By changing the OPSW, the routine can select any return point 
in the interrupted program. 

The control program returns control to the interrupted program by 
loading a PSW constructed from the possibly modified OPSW saved in the 
PIE. 

If a program interruption occurs when the program interruption exit 
routine is in control, the control program exit routine is given 
control. 
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SPIE List Form 

Use the list form of the SPXE macro instr to construct a con- 

trol program parameter list in the form of a program interruption con- 
trol area. 

The description of the standard fprir of SPIE explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of 
the pair of list and execute forms, j^he format description below indi- 
cates the optional arid reguired operahds in the list form only. 

r ■ 7~~T -T-^~~— -.T*- — - — •-; ■ — • -— ■ — -• 1 

I [symbol] j SPI£| Cinterruption exit addressl 1, (interruptiorts) 3,MF=L | 

_i_ J. ±^ ^ _. J 

symbol ^ ■ , . 

is any syioabol valid in the asselhbier language. 

address 

is any address that may be written in an A-type address constant. 

interiruptions 

are one or more decimal digits separated by commas. 

MF=L 

indicates the list form of the SjPIE imacro instruction. 



( ] indicates optional name or operarids. 
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SPIE — Execute Form 

A remote control prcgrair parameter list (prograir interruptions con- 
trol area) is used in, and can be modified by, the execute forir of the 
SPIE macro instruction. The PICA (prograir interruption control area) 
can be generated by the list form of SPIE, or you can use the address of 
the PICA returned in register 1 following a previous SPIE macro instruc- 
tion. If this macro instruction is being issued to reestablish a pre- 
vious SPIE environment, code only the WF operand. 

The address of the remote control program parameter list associated 
with any previous SPIE environment is returned fcy the SPIE macro 
instruction. 



The description of the standard form of SPIE explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of 
the pair of list and execute forms. The forrrat description below indi- 
cates the optional and required operands in the execute form only. If 
the address of a previous PICA is used, only the WF operand should be 
coded. 

r —T T 1 

I (symbol] | SPIE | [interruption exit address ](,( interruptions) ] | 
I I I , MF= ( E, ( con trol program list address)) | 

I I I \ (1) / I 

L J. X J 

r.yiiibol 

is any symbol valid in the assembler language, 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. You may designate the register symbolically or with 
an absolute expression; always code it within parentheses. 

interruptions 

are one or more decimal numbers separated by coirmas. 

MF= (E, /control program list addressl) 
I (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list (program interruption control area). 
The address of the control program parameter list can be coded as 
described under "address," or can be loaded into register 1, in 
which case code MF=(£, (1)). 



[ ] indicates optional name or operand; select one from vertical stack 
within { }. 
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STATUS — Change Subtask Status (VS2 only) 

The STATUS icacro instruction lets the prograirwer change the dispat- 
chal^ility status of one oi: all of his program's subtasks. One use of 
the STATUS macro instruction is to restart suttasks that were stopped 
when ah attention exit rbutine was eh^ 

The STATUS macro instruction is used only in a VS2 environirept . It 
is ignored when it is issued in VSl. 

The STATUS inacrp instruction is written as follows: 

r '■ T T ^- ; . — . — — _^ 

I (syinbol] |STATt)§j|STAET) t ,TCB=address of sub^ tot address] j 

1 ■■■■ I I (STOP / ■ I 

L . X- -X.; . . . — . , — . — J 

START 

indicates that the STOP/START count in the task control block spe^ 
cified in the TCB operand will be decreased by 1. If the TCB 
operand is not coded, the STOP/ST /vrt count is decreased by 1 in 
subtask task control blocks for all the suttasks of the originating 
task. 

STOP 

indicates that the STOP/ START count in the task control block spe- 
cified in the TCB operand will be increased by 1. If the TCB 
operand is not coded, the STOP/START count is increased by 1 in the 
task control blocks for all the subtasks of the originating task. 

TCB= 

specifies the address of a f ullword on a fullword boundary contain- 
ing the address of a task control block that is to have its STOP/ 
START count adjusted. If a register is designated, the register 
must contain the address of the task control block. If this 
operand is not specified, the STOP/START count is adjusted in the 
task control blocks for all the subtasks of the originating task. 

Control is returned to the instruction following the STATUS macro 
instruction. When control is returned, register 15 contains one of the 
following return codes: 

Hexadecimal 

Code Meaning 
00 Succeissf ul. 

04 The specified task control block does not belong to a 

subtask of the originating task. The STATUS macro 
intruction was ignored. 
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1?T IMER — L?et Interval Timer 

Uije the iSTlMER macro ii)Struction to set a ^ rocjranirtied timer to a spe- 
cified time interval (less than 2U hours) or to an interval that will 
expire at a specified tiire of day. The interval is decreased con- 
tinuously. An optional timer completion routine is given control when 
the time interval expires; if no timer completion routine is specified, 
no indication that the time interval has expired is provided. Only one 
time interval is in effect at a time. A second STIMER macro instruction 
issued before the first time interval expires overrides the first 
interval and exit routine. 

The time interval may be a "real-time interval" (measured continuous- 
ly in real time) or a "task time interval" (measured only while the task 
is in execution.) If a real time interval is specified, the task may 
elect to either continue or suspend execution during the interval. If 
the task elects to continue execution, it iray optionally specify an exit 
routine to be given control on completion of the time interval. If the 
task elects to suspend execution, it is restarted at the next sequential 
instruction on completion of the time interval. If a task time interval 
is specified, the task must continue. It may optionally specify an exit 
routine to be given control on completion of the interval. 

The STIMER iracro instruction is written as shown in the following 
format description. The operand combinations in the shaded area of the 
format description may only be used in a VS2 system. 

r -"-T T ■ -r-T ■ .1 

I [symbolJ I STIM£R|iHEALl, timer completion exit address]!! ,DINTVL=address l| 
I I KTASKt , timer completion exit address]/ \, BINTVL=address /| 

I I I^AIT ' |,TUINTVL=address|| 

I 11 ],TOD=address 1| 

i j I Luxoa^Nyse^ I 

L __. X . X 1 

REAL 

is written as shown. It specifies that the timer interval is a 
real-time ' interval and is to te decreased continuously. If the TOD 
operand is coded, the interval expires at the indicated time of 
day. You can also specify a real-time interval by using the WAIT 
operand. 

TASK 

is written as shown. It specifies that the timer interval is a 
task time interval and is to be decreased only when the associated 
task is active. 

WAIT 

is written as shown. It specifies that the time interval is a 
real-time interval and is to be decreased continuously. The job 
step is to be placed in the wait condition until the interval 
expires. 

1 imer coroplet ion exit address 

is the address of the timer completion exit routine to be given 
control after the specified time interval expires. The exit rou- 
tine is given control by means of an interruption of the task that 
was active when the STIMER macro instruction was issued; the rou- 
tine must be in virtual storage when it is required. The contents 



I ] indicates optional name or operand; select one from vertical stack 
within { }. 
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of the registegcs when the exit jrqutine is given Gpntrol are as 
follows' ■ 

Register Contents 

0-1 Control program information. 

2-12 Unpredictable. 

13 Address of a control-prograro-provided save area. 

14 Return address (to the control program). 

15 Address of the exit routine. 

The exit routine is responsi>>le for saving and restoring registers. 
The exit routine executed a^ a suferqutine, and roust return cont:r61 
to the contrbl prpgrairi, 

DINTVL= 

is the address in virtual storage of a doubleword on a doubleword 
boundary containing the time interval. The time interval is pre- 
sented as unpacked decimal digits of the forni: 

HHMMSSth, where: 

HH is hours (24-hour clock); 
MM is minutes; 
SS is seconds; 
t is tenths of seconds; and 

h is hundredths of a second (Hiaxirnuni value 9). 

BINTVL= 

is the address in virtual storage of a fullword on a fullword boun- 
dary containing the time interval. The time interval is presented 
as an unsigned 32-bit binary number; the low-order bit has a value 
of 0.01 second. 

TUINTVI.= 

is the address of a f ullword on a fuHWord boundary containing the 
time interval. The timie ihteryal is presented as an unsigned 32- 
bit binary number; the low^order tit has a value of one tinier^^ 
(26,04166 microseconds), 

TOD= 

is the address of a doubleword on a doubleword boundary containing 
the time of day at which the interval is to be completed. The time 
of day is presented as unpacked decimal digits of the form 
HHMMSSth, If TASK is specified, , the time of day is interpreted as 
though the DINTVL operand had b(een specified, 

MIC= 

is the address of a doubleword on a doubleword boundary containing 
the time interval. The time interyal ; is represented as an unsigned 
64-bit binary number; fait 51 is the low^r^Order digit of the interval 
value. 

Notes ; 

• The time interval specified by an STIMER macro instruction has no 
relation to the time interval specified in an EXEC Statement, 

• If issued by a timer completion exit routine, an STIMER macro 
instruction acts as a NOP instruction in VSl. The STIMER issued 
from a timer completion exit routine in VS2 is accepted, but it must 
not specify the same exit routine cr an infinite loop results. 



STIMEK 



If WAIT is specified in a sys-tem running a single task, no produc- 
tion work is performed while the time interval is in effect. Notify 
the system operator not to cancel the job. 

If the optional exit routine address and WAIT are not specified, no 
indication of completion of the time interval is provided. 

The TTIMER macro instruction provides a facility for determining the 
remaining time interval associated with STIMER. 

When you are using VS, the priorities of other tasks in the sys- 
tem may also affect the accuracy of the time interval measurement. 
If you code REAL or WAIT, the interval is decreased continuously and 
may expire when the task is not active. (This is certain to happen 
when WAIT is coded.) After the time interval expires, assuming the 
task is not in the wait condition for any other reasons, the task is 
placed in the ready condition and competes for control with the 
other ready tasks in the system. The additional time required 
before the task becomes active depends on the relative dispatching 
priority of the task. 
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'MMk~Jrrr....§^ti^iv^:..Tj^-- ■and-Dat-e 

The TIME macro instruction causes the control program to return the 
time bf day and the date. The time of day and date are only as accurate 
as the corresponding information entered by the operator, and the system 
response speed; 

This date is returned in register 1 ias packed decimal digits of the 
form 00 YY DD DC, Where: 

YY is the last ttik) digits ^ the year; 
DDE) is th^ day of the yeir; 

e is a U-iiit sigh character €hM ^iibw^ the data to be unpacked 
and printed. 

The time of day, based on a twenty- four-hour clock, returned in the 
form designated by the operand shown below. For the DEC, BIN, and TU 
operands, the time of day is returned in register 0. For the MIC, 
address operand, the time of day is returned in the specified address, 
and register 0 is set to zero. If th6 operand is omitted , DEC is 
assumed. 

The TIME macro instruction is written as follows : 

T- -T : 1 

DEC 



I [symbol] | TIME | 
I 
I 



BIN 
TU 

MIC, address 



DEC 



BIN 



TU 



MIC 



is %«ritten as shown. Time of day is ireturned in register 0 as 
packed decimal digits of the form: 

BHMMSSth, Where: 

HH is hours ( 2«i hour clock) ; 
MM is minutes ; 
SS is seconds; 

t is tenths of seconds ; and 

h is hundredths of second (maximum value 9) . 



is written as shown. Time of day is returned in register 0 as an 
unsigned 32-bit binary number. Th^ low-order bit is equivalent to 
0. 01 seconds . 



is written as shown. Time of day is returned in register 0 as an 
unsigned 32- bit binary number. The low-order bit is equivalent to 
26.04166 microseconds (one timer unit). 

is written as shown. It requests the time of day in microseconds. 



C 1 indicates optional ncune or operand; select one or none from within 
t 1; ___ indicates an assumed value. 
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address 

is the address of an 8-byte area in storage where the time of day 
is returned in microseconds with bit 51 equivalent to one 
microsecond. 

If the MIC,address operand is specified, register 15 contains one of 
the following return codes when control is returned to the user: 

Hexadecimal 

Code Meaning 
00 Successful. 

OU Unsuccessful. The specified address is not valid. The 

date is stored in register 1; register 0 contains 0. 
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TTIMER — Test Interval Timer 

In VSl, or in VS2 if TU is specified or assumed, the TTIMER macro 
instruction causes the control program to return in register 0 the 
amount of time remaining in a timer interval previously set by an STIMER 
macro instruction. The time remaining is returned as an unsigned 32-bit 
binary number specifying the number of timer units (26 microsecond 
units) remaining in the interval. If a time interval has not been set, 
register 0 contains 0. TTIJjER can also be used to cancel the remaining 
time interval. 

If MIC is specified in a VS2 system, the remaining time is returned 
to the doubleword area specified in the address. Bit 51 of the area is 
the low- order digit of the interval value. If a time interval has not 
been set the area is set to 0. 

The operand combinations in the shaded area of the format description 
may only be used in a VS2 system. 

The TTIMER macro instruction is written as follows: 



i i I Mi V] 

j [symbol] | TTIMER | [CANCEL] |^p^i9tddre68/J 



CANCEL 

is written as shown. It indicates that the remaining time interval 
and exit routine, if any, are to be canceled. If WAIT was coded in 
the STIMER macro instruction that established the interval, the 
task is not taken out of the wait condition. If CANCEL is not 
designated, the unexpired portion of the time interval remains in 
effect. 

TO 

is written as shown. Remaining time in the interval is returned in 
register 0 as an unsigned 32-bit binary number. The low-order bit 
is equivalent to 26.04166 microseconds (one timer unit). 

MIC 

is written as shown. It requests the remaining time in the interv- 
al to be retuned in microseconds. Address is the doubleword area 
on a doubleword boundary where the remaining interval is to be 
stored. 

Note ; For further information about the use of TTIMER, refer to the 
description of the STIMER macro instruction. 

If MIC, address is specified, register 15 contains one of the follow- 
ing return codes when control is returned to the user: 

Hexadecimal 

Code Meaning 
00 The area specified by address contains the time remain- 

ing in the interval. 

OU The area specified is not contained within the reques- 

tor's allocated storage. If cancel was coded, the 
interval was not canceled. 



( ] indicates optional name or operand; indicates an assumed value. 
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WAIT — Wait for One or More Events 

The WAIT macro instruction is used to inform the control program that 
performance of the active task cannot continue until one or more specif- 
ic events, each represented by a different ECB (event control block), 
have occurred. Bit 0 of each ECB must be set to 0 before it is used. 
The control program takes the following action: 



• For each event that has already occurred (each ECB is already post- 
ed) , the count of the number of events is decreased by 1. 



• If the number of events is 0 by the time the last event control 
block is checked, control is returned to the instruction following 
the WAIT macro instruction. 



• If the number of events is not 0 by the time the last ECB is 

checked, control is not returned to the issuing program until suffi- 
cient ECBs are posted to bring the number to 0. Control is then 
returned to the instruction following the WAIT macro instruction. 



The WAIT macro instruction is written as follows: 

J. ^ J. . . ^ 

I (symbol] | WAIT | [number of events, ]fECB=addr ess ) | 



number of events 

is a decimal integer from 0 to 255. Zero is an effective NOP 
instruction; one is assumed if the operand is omitted. The number 
of events must not exceed the number of event control blocks. 

ECB- 

is the address of the event control block representing the single 
event that must occur before processing can continue. The opercuid 
is valid only if the number of events is specified as one or is 
omitted. 

ECBLIST= 

is the address of a virtual storage area containing one or more 
consecutive fullwords on a fullword boundary. Each fullword con- 
tains the address of an event control block; the high-order bit in 
the last word (address) must be set to 1 to indicate the end of the 
list. The number of event control blocks must be equal to or 
greater than the specified number of events. 

Caution : A job step with all of its tasks in a WAIT condition is ter- 
minated upon expiration of the time limits that apply to it. 

Example : You have previously initiated one or more activities to be 
completed asynchronously to your processing. As each activity was 
initiated, you set up an ECB in which bits 0 and 1 were set to 0. You 
now wish to suspend your task via the WAIT macro instruction until a 
specified number of these activities has been completed. 



( ] indicates optional name or operand; select one from vertical stack 
within { > 




L_. 



-JL 



x. 



—J 
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Cbii^letioh of each activity must be made known to the system via the 
POST? macro instruction. POST causjes an addressed ECB to be marked com- 
plete. If completion of the event satisfies the requirements of an out- 
standing WAIT, the waiting task is marked ready and will be executed 
when its priority allows. 

Event Cbntrol filock 

The event control block is used for communication between various 
components of the control program, as well as between processing pro- 
grams and the control program. Ah ISCB is the subject of WAIT and POST 
macro instructions. Figure 58 shbwsi the fprmat of the event control 
block. A description of its fields fbiiow:^ the illustration. 



r— - 
1+0 



+1 



+ 2 



+ 3 



|W|C| 



.X . X- . r 

Figure 58. Event control block 



Bytes and 
Pi splacement Alignnient 
+0 1 



Field 
Name 



.1. . .... 

. . XX xxxx 



Hex- Field Description, Contents, 
iJiq. Meaning 

Awaiting completion of an 

event : 

W - Waiting for completion of 
an event. 

After completion of an event: 
C - The event has completed. 
Completion code. 
One of the following completion 
codes will appear at the com- 
pletion of a channel program; 



Access Methods Except BTAM and 

TCAM. 



7F Channel program has terminated 
without error. (CSW corit^ts 
useful.) 



41 Channel program has terminated 
with permanent error. (CSW 
contents useful.) 

k2 Channel program has terminated 
because a direct access extent 
address, has been violated. 
(CSW contents do not apply. ) 

4u Channel program has been inter- 
cepted because of permanent 
error associated with device 
end for previous request. You 
may reissue the intercepted 
request. (CSW contents do not 
apply . ) 

48 Request element for channel 

program ha been made available 
after it has been purged. (CSW 
contents do not apply.) 
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Bytes and Field Hex. Field Description, Contents, 

Displacement Alignment Name Dig. Meaning 

HF Error recovery routines have 

been entered because of direct 
access error but are unable to 
read home address or record 0. 
(CSW contents do not apply. ) 



BTAM 



7F Normal completion. 

41 Completed with an I/O error. 

48 Enable command halted, or, I/O 
operation purged. 

TCAU 

7F Normal completion (work unit in 
work area) . 

70 The SETEOF macro instruction 

was issued in the message com- 
mand program (no work unit in 
work area) . 



50 Message was not found when the 
READ macro instruction was 
issued in conjunction with the 
POINT macro instruction to 
retrieve a message. 

5C Congested destination message 
queue data set (write only) . 

58 Sequence error. 

54 Invalid message destination. 

52 Work area overflow. 

02 End-of -queue condition (not 
end-of-f ile) . 

01 Read-ahead queue empty, but 
destination queue not empty. 

40 Data is on read- ahead queue. 

♦1 3 Awaiting completion of an 

event: 

Request block address. 
After completion of the event: 
Zeros, or remainder of comple- 
tion code. 
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WftlTR — - Wait for One or More Events 

The MAITR macro instruction is coded and is executed in exactly the 
8£une manner as the WAIT macro instruction. 
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WTL — Write to Log 

The WTL macro instruction causes a message to be written to the sys- 
tem log. The message can include any character that can be used in a 
C-type (character) DC statement, and is assembled as a variable- length 
record. 

The standard form of the WTL macro instruction is written as shown 
below. Information about the list and execute forms follows this 
description. 

r — -r r 1 

I [symbol] I WTL | 'message* | 
L :. X.-. X . J 

message 

is the message to be written to the system log. The message must 
be enclosed in apostrophes, which will not appear in the log. The 
message is limited to 126 characters. 



I i indicates optional name. 
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WTL — List Form 

Use the list form of the WTL macro iiistruction to construct a control 
program parameter list. The message opeirand must be provided in thei 
list form of the macro instruction. tI^^ dels cript ion of the standard 
form of the WTL macro prbyides the reguirements for writing the message. 

The list form of the WTL macro is written as follows: 
f [symbol] J WTL J 'message* ,MF=L | 

message 

is any character string valid in a c-type (character) DC 
instruction. 

MF=L 

indicates the list form of the WTL macro instruction. 



[ ] indicates optional name. 
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WTL — Execute Form 

A remote control program parauneter list is used in the execute form 
of the WTL macro instruction. The parameter list can be generated by 
the list form of WTL. You cannot modify the message in the execute 
form . 

The execute form of the WTL macro is written as follows: 

r ~- r- r • 1 

I [symbol] | WTL | MF=(E, (control program list address)) | 

I I I I (1) / I 

L ± J. , I 



indicates the execute form of the macro instruction using a remote 
control program parameter list. The address of the control program 
parameter list can be loaded into register 1, in which case code 
MF=(E, (1)). If the address is not loaded into register 1, code it 
as any address that is valid in an RX-type instruction, or one of 
the general registers 2-12, previously loaded with the address. 
You can designate a register symbolically or with an absolute 
expression; always code it within parentheses. 



(] indicates optional name; select one from vertical stack within { }. 



MF=(E, (control program list address)) 




(1) 
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WTO Write t-o Operator (VSl Without Multiple Console Support) 

The WTO macro instructioh causes a niessage to be written to the 
operator's console. 

The standard form of the WTO macro instruction is written as shown 
below. The operands in the shaded ar<^a of the format descriptiph are 
used in operating systems that include the Multiple Console Support 
(MCS) option; they are ignored if coded in an operating system that does 
not include the MCS option, except for descriptor codes 1 and 2, and 
routing code 11 which designates a Write-to-Prograimmer request. Routing 
and descriptor codes are described in Appendix C. 

If you code a WTO macro instruction with a routing code of 11 in an 
operating system without MCS, this message will go to the system message 
class data set and not to the operator's console. If you want the mes- 
sage to also appear on the operator's console, code the appropriate 
routing code (as described in Appendix C) in addition to routing code 
11. For example: 

WTO 'message*, ROUTCDE=ll Results in a Write-to-Programmer message. 

The message will appear only on the sys- 
tem message class data set. 

WTO 'message', ROUTCDE=(x, 11) Where x represents any valid routing code 

other than 11 (see Appendix C for a 
description of these codes) . Results in 
both a Write-to-Programmer and a Write- 
to-Operator message. The message will 
appear on both the system message class 
data set and on the operator's console. 

The operands in the nonshaded area can be coded with any configura- 
tion of the operating system. Information about the list and execute 
forms follows the write-up for WTO with MCS support. 

r — r— — T " — -• ■■ 1 

I [symbol] | WTO | 'message' tfB0DTCI)B«Cnil]iil>erC«Ilunber*4 ,3) | 

L A Jfcii .: :_^^«i_iiJ._.l._.: . . : — ._. . — J 

message 

is the message to be written to the operator's console. The mes- 
sage must be enclosed in apostrophes which will not appear on the 
console. It can include any character that can be uised in a 
character (C-type) DC instruction, except the New Line control 
character (punch combination 11-9-5). The maximum message length 
is 120 characters (bytes) for a user non-action message. All other 
messages may be as long as 121 bytes. The meissage is assembled as 
a variable- length record. 



[ ] indicates optional name and operands. 
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WTO — Write to Operator (V31 With Multiple Cons o le Support) 

The WTO iiiacro instruction causes a iressage to be written to one or 
more operator consoles. 

The standard form of the WTO macro instruction is written as shown 
iu low- Inform. it itin .ibnut the li;;! and execute forms tollows this 
doi;c;i iption. 

r T ■- T 1 

I [symbol] | WTO | (' message' ) | 
I I I U 'text* [, line type]) ,.. .j | 
I 11 [ ,ROUTCDE= (number [, number] ,...) 1 | 
I I I [, DESC=nurober] | 
L ._x X J 

message 

is the message to be written to one or more operator consoles. The 
message must be enclosed in apostrophes; the apostrophes do not 
appear on the console- It can include any character that can be 
used in a character (C-typo) DC instruction, except the New Line 
control character (punch combination 11-9-5). The maximum message 
length is 120 characters (bytes) for a user non-action message. 
All other messages may be 121 characters. The message is assembled 
as a variable-length record- 
Note: All WTO messages with a descriptor code of 1 or 2 are action mes- 
sages. An asterisk is printed before the first character of an action 
message to indicate a need for operator action . 

( 'text' [ ,line type] ) 

is used to write a multiple-line message to the operator. The mes- 
sage may be up to ten lines long (if more than ten lines are coded 
in the macro, the macro is not generated and an MNOTE is issued) . 
This limit does not include the control line (message IEE932I), see 
item C below. 



text 

is One line of the multiple-line message to be passed to the opera- 
tor. A line consists of a character string enclosed in apostrophes 
(the apostrophes do not appear on the operator's console). Any 
character valid in a c-type DC instruction may be coded except a 
New Line control character. The maximum number of characters 
depends on which line type is specified (see Figure 59). 

line type 

is an alphabetic indicator defining the type of information con- 
tained in the 'text' field of each line of the message: 

C 

indicates that the 'text' parameter is the text to be contained 
in the control line of the message. The control line normally 
contains a message title. C may only be coded for the first line 
of a multiple-line message. If this parameter is omitted and 

descriptor code 9 is coded, the system generates a control line 
(message IEE932I) containing only a message identification num- 
ber. The control line remains static during framing operations 
on a display console (provided that the message is displayed in 
an out-of -line display area). 



I J indicates optional name and operands. 
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■ L 

indicates that the 'text* parameter is a label line. Label lines 
contain message heading information; they remain static during 
framing operations on a display console (provided that the mes- 
sage is displayed in an out-of-line display area). Label lines 
are optional. If coded, lines irust either immediately follow the 
control line or another label line or be the first line of the 
roultiple-line message if there is no control line. Only two 
label lines may be coded per message. 

D 

indicates that the 'text* parameter contains the information to 
be conveyed to the operator by the multiple-line inesuaqe. During 
framing operations on a display console^ the data lines are 
paged. 

DE 

indicates that the 'text* parameter contains the last line of 
information to be passed to the operator. 

■■■ ,E ■ ■ 

indicates that the previous line of text was the last line of 
text to be passed to the operator. The 'text* parameter, if any, 
coded with a line type of E is ignored. 

ROUTCDE= 

specifies the routing codes to be assigned to the message. '"Num- 
ber " must be a routing code from 1 through 16* Routing codes are 
defined in Appendix C. If the ROUTCDE operand is omitted but DESC 
is specified, routing code 2 is assigned. 

DESC= 

specifies the message descriptor code (s) to be assigned to the roes- 
sage. "Number" must be a descriptor code from 1 through 16. 
Descriptor codes are defined in Appendix C. If the DEr>C operand is 
omitted, no descriptor code is assigned. 

If both the ROUTCDE and DESC parameters are omitted, no routing or 
descriptor codes are assigned. 

When control is returned, general register 1 contains the identifica- 
tion number (24 bits and right- justified) assigned to the message. 

Note: The two operands available to the system programmer are MSGTYP 
and MCSFLAG. They are discussed in Appendix C. 



T : • — • T ■ — ' • -y- ; ^-|- 

I Line Type | VSl | VS2 | 

________ + -_ _ __ _-_| 

I G I 31 characters | 34 characters | 
I L I 71 characters [ 70 characters | 
ID I 71 characters j 70 characters j 
j DE 1 71 characters | 70 characters | 
|. X _ X _______ .... ^ 

I Note : L, D, and DE lines displayed on a 2250 display console will be | 
(truncated to 70 characters. j 

L - . . . . . _J 



Figure 59. Maximum 'text* field charaeters in a multiple-line WTO 
message 
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Return codes from execution of a WTO using the multiple- line feature are 
as follows: 

Hexadecimal 



Code Meaning 
00 No errors encountered. 

04 Number of lines passed was 0. Request is ignored. 

08 ID passed in register 0 does not match any on queue. 

Request is ignored. 

12 Invalid line type- An end has been forced at the point 

of the error except if the first line is an E line, in 
which case the request is ignored. 

16 Request specified routing code 11 (WTP) . Request is 

ignored. 

20 MLWTO request to hard copy only. Request is ignored. 



Note: No return codes are issued by the WTO service routine if the 
MLWTO feature is not used. 
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WTO — Write to Operator (VS2 With Multiple Console Support) 

The WTO macro instruction causes a iressage to be written to one or 
more operator consoles. 

The standard form of the WTO macro instruction is written as follows: 

r —-—I— T— -■ ■■ : -1 

I (symbol] i WTO | f' iressage* I | 

1 I I \( *text« l,line type!) , . . ./ | 

I I 1 I, ROUTCDE= (number I, number ), ...)) | 

I 1 I I, DESC=( number I, number 1, ., .)] | 

I I 1 [,AREAID=char] I 

L . X X ■ . J 

message 

is the message to be written to one or more operator consoles. The 
message roust be enclosed in apostrophes (the apostrophes do not 
appear on the console) . It can include any character that can be 
used in a character (C-type) DC instruction, except the New Line 
control character (punch combination 11-9-5). The maximum message 
length is 12U characters (bytes). The message is assembled as a 
variable- length record. 

Note: All WTO messages with a descriptor code of 1 or 2 are action mes- 
sages. An indicator is printed before the first character of an action 
message to indicate a need for operator action, but this does not reduce 
the maximum length of an action message. 

('text' [, line typel) 

is used to write a multiple-line message to the operator. The mes- 
sage may be up to ten lines (if more than ten lines are passed by a 
program, the system truncates the message at the end of the tenth 
line) . This limit does not inlude the control line (message 
IEE932I) . 

text 

is one line of the multiple-line iressage to be passed to the opera- 
tor. A line consists of a character string enclosed in apostrophes 
(the apostrophes do not appear on the operator's console). Any 
character valid in a C-type DC instruction may be coded except a 
New Line control character. The naximum number of characters 
depends on which line type is specified (see Figure 59). 

line type 

is an alphabetic indicator defining the type of information con- 
tained in the 'text* field of each line of the message: 

C 

indicates that the 'text' parameter is the text to be contained 
in the control line of the message. The control line normally 
contains a message title. C may only be coded for the first line 
of a multiple- line message. If this parameter is omitted and 
descriptor code 9 is codled, the system generates a control line 
(message IEE9323;) containing only a message identification num- 
ber. The control line reinains static during framing operations 
on a display console (provided that the message is displayed in 
an out-of- line display area) . 

L 

indicates that the 'text' parameter is a label line. Label lines 
contain message heading information; they remain static during 
framing operations on a display console (provided that the mes- 
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sage is displayed in an out-of-line display area) . Label lines 
are optional. If coded, lines irust either imitiediately follow the 
control line or another label line or te the first line of the 
multiple- line message if there is no control line. Only two 
label lines may be coded per message. 

indicates that the 'text" parameter contains the information to 
be conveyed to the operator by the multiple-line message. During 
framing operations on a display console, the data lines are 
paged. 

DE 

indicates that the 'text* patameter contains the last line of 
information to be passed to the operator. 

E 

indicates that the previous line of text was the last line of 
text to be passed to the operator. The 'text* parameter, if any, 
coded with a line type of E is ignored. 

ROUTCDE= 

specifies the routing codes to be assigned to the message. Number 
must be a routing code from 1 through 16. (Routing codes are 
defined in Appendix C) . If the ROUTCDE operand is omitted but the 
DESC is specified, routing code 2 is assigned. 

DESC= 

specifies the message descriptor code or codes to be assigned to 
the message. Number must be a descriptor code from 1 through 16. 
(Descriptor codes are defined in Appendix C.) If the DESC operand 
is omitted, no description code is assigned. 

AREAID= 

I* 

specifies a display area of the console screen on which a multiple 
line message is to be written- "char" may be any alphabetic 
character A-Z. 

Z designates the message area (the screen's general message area, 
rather than a defined display area); it is assumed nothing is 
specified. 

The AREAlD parameter is only useful for out-of-line (descriptor 
code 8 and 9) MLWTO messages which are to be sent to CRT consoles. 

If both the ROUTCDE and DESC parameters are omitted, the routing code 
specified in the OLDWTOR operand of the system generation SCHEDULR macro 
instruction is assigned. If the OLDWTOR operand is omitted, no routing 

code is assigned. 

When control is returned, general register 1 contains the identifica- 
tion number (2^ bits and right- justified) assigned to the message. 

Note : The two operands available to the system programmer are MS(3TYP 
and MCSFLAG. They are discussed in Supervisor Services and Macro 
Instructions for the System Programmer . 
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WTO 

Return codes from execution of a WTO using the multiple- line f feature are 
as follows: 



Hexadecimal 
Code 
00 

OH 

08 

12 



16 



20 



Meaning 

No errors encountered. 

Number of lines passed was 0. Request is ignored. 

ID passed in register 0 does not match any on queue. 
Request is ignored. 

Invalid liiie type. An end has been forced at the point 
of the error except if the first line is an E line, in 
which case the request is ignored. 



Request specified routing code 11 (WTP) 
ignored. 



Request is 



MLWTO request to hard copy only. Reiquest is ignored. 



Note: No return codes are issued by the WTO service routine if the 
MLWTO feature is not used. 
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WTO - L Form 

W TO — List Form 

Use the list form of the WTO macro instruction to construct a cohtrol 
program parameter list. The message operand must be provided in the 
list form of the macro. The description of the standard form of the WTO 
macro provides the requirements for writing the message. 

The format description below indicates the optional and required 
operands for the list form. The operands in the shaded area of the for- 
mat description are used with the Multiple Console Support (MCS) option; 
they are ignored if coded without MCS, except routing codes 1 and 2 
which designate a Write- to-Master Console and routing code 11 which 
designates a Write-to- Programmer request- (See the standard form of the 
WTO macro for a description of this exception.) 

^ . ^ ^ ^ 

I [symbol] 1 WTO | i( ' text' (, line type] ),.. | 
I I I I 'message' f ) 

I II {♦KOUl?C0B«(tiumbe3r£, number - 1 

II I tj^j3^C«»»t3g»toearltM£'"-L . ^ I 

I ; X t ,1.1. 1, ,1 - ■■■luiiimiiiliuuj. ,„., „., I, , I I, , ^ ML llufi'rffcim''iif<<^ri>tf"fril 

message 

is a character string valid in a character (C-type) DC instruction, 
except the line control character (punch combination 11-9-5). 

•text' 

is a character string valid in a C-type DC instruction except for 
the New Line control character. 

line type 

is an alphabetic symbol indicating the type of information con- 
tained in the 'text" parameter. 

MF=L 

indicates the list form of the WTO macro. 

ROUTCDE= 

specifies the routing codes to be assigned to the message. 

DESC--= 

specifies the message descriptor code to be assigned to the 
message. 

Note : Two additional operands available to the system programmer 
(MSGTYP and MCSFIAG) are discussed in Appendix C. 



[ ] indicates optional name or operand. 
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WTO - E Form 



WTO Execute jyorm 

A remote control program parameter list is used in the execute form 
of the WTO macro instruction. The parameter list can be generated by 
the list form of WTO. The message cannot be modified in the execute 
form of the macro - 

The execute form of the WTO macro is written as follows: 

r -~- r---——T-.~—r— — ---.—-r—— ■ — i 

I (symbol] | WTO |MF=(E,j control program list address >) | 

I I I \ (1) . I I 
L ;_x— A . '. . . —J 

MF=(E, /control program list address \) 

t (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list. If you have loaded the address of 
the control program parameter list into register 1, code 
MF=(E, (1)). If the address is not loaded into register 1, code it 
as any address that is valid in an RX-type instruction, or one of 
the general registers 2-12, previously loaded with the address. 
Designate the register symbolically or with an absolute expression; 
always code it within parentheses. 



[ ] indicates optional name; select one from vertical stack within { }- 
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WTOR 



WTOR 

Write to Operator With Reply (Without Multiple Console Support) 



The WTOR macro instruction causes a message requiring a reply to be 
written to the operator's console, and provides the information required 
by the control program to return the reply to the issuing program. 

The standard form of the WTOR macro instruction is written as shown 
below. The operands in the shaded area of the format description are 
used in an operating system that includes the Multiple Console Support 
(MCS) option; they are ignored if coded in an operating system that does 
not include the MCS option, except for descriptor codes 1 and 2, and 
routing code 11 which designates a Write- to- Programmer request. If a 
WTOR message is coded with a routing code of 11 in an operating system 
that does not include the MCS option, the message portion of the message 
will go to both the system message class data set and the operator's 
console. The operands in the nonshaded area can be coded with any con- 
figuration of the operating system. Information about the list and 
execute forms follows this description. 



I [symbol] j WTOR 

1 i 
I i 



j 'message* , reply address, length ofjcegl] 
ecb address I 




message 

is the message to be written to the operator's console. The mes- 
sage must be enclosed in apostrophes (the apostrophes do not appear 
on the console). It can include any character that can be used in 
a character (C-type) DC instruction, except the New Line control 
character (punch combination 11-9-5) . The maximum message length 
is il7 characters (bytes). The message is assembled as a variable- 
length record. No requirement exists to pad the message with 
blanks. 



Note: All WTOR messages are action messages. An indicator is 
printed before the first character of an action message to indicate 
a need for operator action. 

reply address 

is the address in virtual storage of the area into which the con- 
trol program is to place the reply. The reply is left- justified at 
this address. 

length of reply 

is the length, in bytes, of the reply message. The maximum reply 
length is 119 bytes. The minimum reply length is one byte. 

ecb address 

is the address of the event control block to be used by the control 
program to indicate the completion of the reply. 



t ] indicates optional name or operand. 
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WTOR 

WTOR — Write to Operator With Reply (With Multiple Console Support> 

The WTOR iriacro instruction causes a message requiring a reply to be 
written to one or more operator consoles and the system log, and pro- 
vides the information required by the control program to return the 
reply to the issuing program. 

The standard form of the WTOR macro is written as follows. Informa- 
tion about the list and execute forms follows this description. 

r ' — ■ T T — ■ —' ■ • : T ■ 

I [symbol] | WTOR | • message* , reply address, length of reply, | 
I I I ecb address t,ROUTCl)E=( number [, number. ..] ) | 

I I I [,DESC-number] | 

L — X. J. ^ . . . 

message 

is the message to be written to the operator's console- The mes- 
sage must be enclosed in apostrophes, which will not appear on the 
console. It can include any character that can be used in a 
character (C-type) DC instruction, except the New Line control 
character (punch combination 11-9-5). The maximum message length 
is 117 characters (bytes) in VSl, 121 characters in VS2. The mes- 
sage is assembled as a variable- length record. No requirement 
exists to pad the message with blanks. 

Note: All WTOR messages are action messages. An indicator is 
printed before the first character of an action message to indicate 
a need for operator action. 

reply address 

is the address in virtual storage of the area into which the con- 
trol program is to place the reply. The reply is left- justified at 
this address. 

length of reply 

is the length, in bytes, of the reply message. The maximum reply 
length is 115 characters when the operator enters REPLY id, 'reply* 
and 119 characters when the operator enters R id, ' reply The 
minimum reply length is one byte. 

ecb address 

is the address of the event control block to be used by the control 
program to indicate the com.pletion of the reply. 

ROUTCDE= 

specifies the routing codes to be assigned to the message. Number 
must be a routing code from 1 through 16. Routing codes are 
defined in Appendix C. If the ROUTGDE operand is omitted but the 
DESC operand is specified, routing code 2 is assigned. 

DESC= 

specifies the message descriptor code(s) to be assigned to the mes- 
sage. Number must be a descriptor code from 1 through 16. Descri- 
ptor codes are defined in Appendix C. If the DESC operand is 
omitted, no descriptor code is assigned. 

If both the ROUTGDE and DESC operands are omitted, no routing or 
descriptor codes are assigned. 



[ ] indicates optional name or operand. 
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WTOR 



When control is returned, general register 1 contains the identifica- 
tion number (24 bits and right-justified) assigned to the message. 

Note : The two operands available to the system progranuner are MSGTYP 
and MCSFLAG. They are discussed in Appendix C (VSl) and in VS2 
Planning and Use Guide. 
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WTOR List Form 

Use the list form of the WTOR macro instruction to construct a con- 
trol program parameter list. The mesis age operand must be provided in 
the list form. 

The description of the st^^ndard fbrm of the wToR, ibacr^ prbvidei^ the 
t^guirements for writing the me&fsage ihd the (explanation of the fianction 
of each operand. The deiscriptioh of the standard form also indicates 
whibh Operands are toteliy optional and which airie reguired in at least 
one of the pair of list and execute foims. The format deiscriptioh below 
indicates the optional and required operands in the list form only. The 
operands in the shaded area of the format descriptions are used with the 
Multiple Console Support (MCS) option; they are ignored if coded Without 
MCS, except routing codes 1 and 2 which designate a Write-to-Master- 
Console and code 11 in the RODTCDE operand which designates a Write- to- 
Programmer request. (See the standard form of the WTOR macro instruc- 
tion for a description of this exception.) 

The list form of the WTOR macro is written as follows s 

I (symbol] | WTOR | 'message* , (reply address] , (length of reply] | 
I I I , [ecb address] 1 

symbol 

is any symbol valid in the assembier language, 
address 

is any address that can be written in an A-^type address constant, 
length 

is any absolute expression valid in the assembler language, 
message 

is a character string valid in a character (C-type) DC instruction 
except the line control character (puhch combination 11-9-5). 

RODTCDE= 

Specifies the routing codes to be assigned to the message. 

DESC= 

specifies the message descriptor oode to be assigned to the 
message. 

MF=L 

indicates the list form of the WTOR macro. 

Note ; Two additional operands tMSGTYP and MCSFLAG) available to the 
system progreuraner are discussed in App^hdixC (VSl) and VS2 Planning 
and Use Guide. 



( ] indicates optional ncune or operand. 
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WTOR - E Form 



WTOR — Execute Form 

A remote control program parameter list is used in the execute form 
of the WTOR macro instruction- The parameter list can be generated by 
the list form of WTOR. 

The description of the standard form of the WTOR macro provides the 
explanation of the function of each operand. The description of the 
standard forin also indicates which operands are totally optional and 
which are required in at least one of the pair of list and execute 
forms. The format description below indicates the optional and required 
operands in the list form only. The comma before the first operand is 
required to indicate the absence of the message operand, which is not 
allowed in the execute form. 

The execute form of the WTOR macro is written as follows: 

r-^—- — T T ■■ ■ ""1 

I [symbol] | WTOR | , [reply address] ,[ length of reply], [ecb address] | 
I I 1 ,MF=(£, (control program list addressp | 

lilt (1) / I 

L X X J 

symbol 

is any symbol valid in the assembler language. 

address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. Designate the register symbolically or with an 
absolute expression; always code it within parentheses. 

length 

is any absolute expression that is valid in the assembler language, 
or one of general registers 2 through 12, previously loaded with 
the indicated value. Designate the register symbolically or with 
an absolute expression; always code it within parentheses. 

MF= (E,/ control program list address \) 
\ (1) / 

indicates the execute form of the macro instruction using a remote 
control program parameter list. The address of the control program 
parameter list can be coded as described under "address," or can be 
loaded into register 1, in which case code MF=(£, (1)). The para- 
meter list must be aligned on a fullword boundary. The list form 
of WTOR provides this alignment . 



[ ] indicates optional name or operand; select one from vertical staclc 
within { I . 
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XCTL 

XCTL Pass Control to a Program in Another Load Module 

The XCTL macro instruction causes control to tie passed to a specified 
entry point in another load module; the entry point name must be a memb- 
er name or an alias in a directory of a partitioned data set. The load 
module containing the entry point is brought into storage if a usable 
copy is not available. The storage occupied by the load module that 
issued the XCTL is eligible for reassignment by the control program if 
no other requirement exists for that load module. The program executing 
the XTCL macro instruction is logically, removed from the act i ye task, 
and the program gaining control is established as a subprogram of the 
program (system or user) that placed the issuer of XCTL into executibn. 

No return is made to the program issiiing the XCTL macro instructibn; 
the responsibility count tor the load module containing the XCTL macro 
instruction is lowered by 1. A return to the program that placed the 
issuer of XCTL into execution is required for successful completion of 
the task. For this reason, registers 2 through lU, the program inter- 
ruption control area, and the program mask must be restored to the con- 
ditions that existed when the load module received control before the 
XCTL macro instruction can be issued. If the specified entry point can- 
not be located, the task is abnormally terminated. 

The standard form of the XCTL macro instruction is written as shown 
below. Information about the list and execute forms follows this 
description. 

r — ' T T : — ■ — ^ ■ — " ^ — 1 

I [symbol] | XCTL | ( (regl [ ,reg2] ) 1 , ^EP=symbol )| 
I 11 ^EPLOC=address of nanie V| 

I 11 (DE=address of list entry || 

I j I [,DCB=dcb address] | 

t X. — . X_„ : . _. : -: . . ___J 

(regl, reg2) 

is the range of registers from 2 through 12 to be restored from the 
save area pointed to by register 13. The value of the regl operand 
must be less than the value of the reg2 operand. If the reg2 
operand is omitted, only the register specified is loaded; if iioth 
operands are omitted, the contents Of the registers are not 
altered. 

EP= 

is the entry point name in the program to be given control . The 
name must be padded with blanks on the right to eight bytes i 
necessary. If the specified entry point cannot be found, the task 
is abnormally terminated. 

EPLOC= 

is the address of the entry point name described above. Pad the 
name with blanks to eight bytes, if necessary. 

DB= 

is the address of the name field of a 5 8-byte list entry for the 
entry point name. The list entry is constructed using the BLDL 
macro instruction using a length specification of 58 bytes. The 
DCB operand must indicate the same data control block Used in the 
BLDL macro instruction. 



[ ] indicates optional name or operand; select one from vertical steick 
within { }. 
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XCTL 



DCB= 

is the address of the data control block for the partitioned data 
set containing the entry point name described above. The DCB must 
not be defined in the program issuing the XCTL. 

If the DCB operand is omitted or if DCB=0 is specified when the 
XCTL macro instruction is issued by the job step task , the data 
sets referred to by either the STEPLIB or JOBLIB DD statement are 
first searched for the entry point name. If the entry point name 
is not found, the link library is searched. 

If the DCB operand is omitted or if OCB=0 is specified when the 
XCTL macro instruction is issued by a subtask, the data sets asso- 
ciated with one or more data control blocks referred to by previous 
ATTACH macro instructions in the subtasking chain are first 
searched for the entry point name. If the entry point name is not 
found, the search is continued as if the XCTL had been issued by 
the job step task. 
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XCTL - L Form 



XCTL ■ — List Form 

Two parameter lists are used in an XCTL macro instruc±ion: a control 
program parameter list and an optional problem program parameter list. 
Only the control program parameter list can be constructed in the list 
form of XCTL. Address parameters to be passed in a parameter list to 
the problem program cari be provided using the list form pf the GALL 
macro instruction. This par^eter list can be referred to in tiie 
execute form of xcTL. 

The description of the standard fprni of XCTL exjplains the function of 
each ojperand. The description of the standard form also indicates yhich 
operands are always optional and which are required in at ledst one of 
the pair of list and execute forms. The format description below indi- 
cates the optional and required operands in the list form only. 

r T- — — T ^ — — --— 1 



'EP=symbol "|t,DCB=dcb address] | 

EPLOC=^address of name | 

DE=addreiss of list en try j | 

L i |_'SF=L I 



I [symbol] | XCTL 
i i I 

I i i 



symbol 

is any symbol valid in the assembler language, 
address 

is any address that may be written in an A~type address constant. 

SF=L 

indicates the list form of the XCTL macro. 



[ ] indicates optional name or operands; select one or none from yertic- 
al stack within CI. 
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XCTL - E Form 



XCTL — Execute Form 

Two parameter lists are used in the XCTL macro instruction; a control 
program parameter list and an optional problem program parameter list. 
Either or both of these pareimeter lists can be remote and can be 
referred to, and modified by, the execute form of XCTL. If only the 
problem program parameter list is remote, operands that require the con- 
trol program parameter list cause that list to be constructed inline as 
pari: of the macro expansion. If only the control program parameter list 
is remote, no problem program parameters, including the regl,reg2 
operand, can be specified 

The description of the standard form of XCTL explains the function of 
each operand. The description of the standard form also indicates which 
operands are always optional and which are required in at least one of 
the pair of list and execute forms. The format description below indi- 
cates the optional and required operands in the execute form only. 



[symbol] 



XCTL 



[ , DCB=dcb address ] 



[(regl[,reg21)) 
, EP=symbol 

, EPLOC=address of name 
,DE=address of list entry 
,MF= (E,( problem program list address)) ^ 

I (1) / 

,SF= (E,( control program list address!) 

\ (15) / 

, MF=(E, /address \) ,SF= (E,/ address U 

I (1) ( \ (15) / 



symbol 

is any syniboi valid in the assembler language - 
address 

is any address that is valid in an RX-type instruction, or one of 
general registers 2 through 12, previously loaded with the indi- 
cated address. Designate the register symbolically or with an 
absolute expression; always code it within parentheses. 

MF=(E,i problem program list address I) 
^ (1) ' 

indicates the execute form of the macro instruction using a remote 
problem program parameter list . Any control program parameters 
specified are provided in a control program parameter list expanded 
in line. The address of the problem program parameter list can be 
coded as described under "address," or can be loaded into register 
1, in which case code t4F=(E, (1)). 



SF= (E, ^control program list address i) 



(15) 



indicates the execute form of the macro instruction using a remote 
control program parameter list . No problem program pareimeters can 
be specified. The address of the control program parameter list 
can be coded as described under "address," or can be loaded into 
register 15, in which case code SF=(E,(15)). 



I 1 indicates optional name or operand; select one from vertical stack 
within ( >; select one or none from vertical stack within C ]. 
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XChj - E Form 



MF=(E, / address I) ,SF=(E, (address V) 
' (1) / \ (15) f 

indicates the execute form of the macro instruction using both a 
remote problem program parameter list and a remote control program 
parameter list. The addresses of the parameter lists are coded or 
loaded intd registers 1 and 15, as explained above. 
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APPENDIX A; SUMMARY OF OPERANDS 



Appendix A indicates how each operand may be coded in the standard 
and, where applicable, in the list and execute foritis of each macro 
instruction. For example, in ATTACH macro instruction the DCB operand 
may be coded in the standard (S) form using rt^gisters 2-12 or as an A- 
type address constant, in the list (L) fcrir as an A-type address con- 
stant, and in the execute (E) form using registers 2-12 or as an RX-type 
address constant. Only the indicated irethods of coding should be used. 



ABBREVIATION S USED IN APPENDIX A 



Abbreviation Meaning 

Sym Any symbol valid in the assembler language. 

Dec Dig Any decimal digits, up to the value indicated in 

the associated macro instruction description. 
If both Sym and Dec Dig are checked, an absolute 
expression is also allowed - 

Register A general register, always coded within paren- 

theses, as follows: 

(2-12) - one of the general registers 2 through 12, pre- 
viously loaded with the right-adjusted value or 
address indicated in the macro instruction 
description. The unused high-order bits must be 
set to zero. The register may be designated 
symbolically or with an absolute expression. 

(1) - general register 1, previously loaded as indi- 
cated above. Designate the register as (1) 
only . 

(0) - general register 0, previously loaded as indi- 
cated above. Designate the register as (0) 
only. 

RX-type Any address that is valid in an RX-type instruc- 

tion (for example, LA) may be designated. 

A-type Any address that may be written in an A-type 

address constant may be designated. 
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I I I Written as j 

I I |_- ^ ____.„_^____^ ^ 

I I 111 Register j | | 

I I I I l -T T 1 |A-type| 

I Macro I II Dec I (2- j | |RX- |adcon | 

I Instruction I Qperands j Syin | Dig j 12) j (1) | |0) |type|type | 

I ABEND I completion code | S | S | s ( s | | | \ 

I l- .— . _-___„_4. X ^X___^_i.__ x_ X. — -±- 

I I DUMP written as shown | 

I |_„__.__„___. ^.„|_ .____.____„__________„_._______^ 

I I STEP I written as shown 

. _+_„___________^ _ 

I ATTACH I ASYNCH= | YES or NO | 

I f f — T X : — T ^-T T — -r- ^ 

I I DCB= I I I S e I I I E I S L I 

I j. 1 ^. ^ ^ 1 ^ 

I I DE= I I |SE| I |E|SL| 

I ^ ^ ^ ^ 1 ^ ^ 1 ^ 

I I DPMOD= |SLE|SLE|SE| | j | j 

] I- + + + -i -+ + + -I 

I I ECB= I I I S E I I I E I S L I 

I ^ ; ^ 1 1 ^ 1 ^ ^ 

I I EP= |S L E| I I 1 I I I 

I . V . ; — + + + +— — + + ^ 

I I EPLOC= I I I S E I I I E I S L I 

I ^ ^ 4. 1 ^ ^ _| 4 

I I ETXR= I I I S E I I I E I S L I 

I ^ ______ 1--^ X —X x__ X x_ X 4 

I I FPREGSA= I YES or NO j 

I I" • ■ • + T T —r T ■ ^^T T ^ 

I I GSPL= II I S E I I I E I S L I 

I y ___ ____4._____^ ^ 1 1 1 1__ 4 

I I GSPV= )S L E|S L E| S E I | | | 1 

I |. _ _ ____^_^ 4.__. — 4._____l_____4. 1 ^_ 4 

I I LPMOD= |S L E|S L E| S E I | | | | 

I I PARM= I I I S E I J ! E t S ] 

j I— . . ^ X X -^X- X X X. . ^ 

I I PURGE= IQUIESCE, HALT, or NONE | 

I \. . ^ y .y ^. y— ^ y-. ^ ^ 

I I SHSPL= II I S E I I I E |S L I 

I ^__ ^ _ 4._____|_____| + 1 ^__4. + 

I I SHSPV= |SLE|SLE|SE| | | | | 

I l.__ _ : ^ + 4. 1 1_ 1 

I I STAI= I I I S E I I I E 1 S L I 

I |. __^ 4. X X __X_. X X____X 4 

I I SZERO= J YES or NO | 

I I" ■ ■ : ■ 'f- — T " — T ■ — T T T- T ■ -f 

I I TASKLIB= I I I S E I j | E |S L j 

I |. _____ ^ X x_: X X x__-_x . 4 

I I TQE= \ YES or NO | 

I ^ ^__. ^__+____ -_: _ 4 

I j VL=1 I written as shown | 

y 4 f — T T T T T T ^ 

I CALL I entry point name . | S E | | | | | | | 

I y _ _ _ !__. +— ~+ + + i + -I 

I I address parameters | | | S E | | I E | S L | 

I J. . ____-,.^ . : I . — X X x_ _x_. — — x_^ — X 

I I VL {written as shown j 

I y . ._ ; ^ ^ J. -J. ^ y. y. 4 

I I ID= I S E I S E I II I I I 

y.. __ 1 ___-_+__ ^ +— — + + + + 4 

I CHAP j priority change value | S | S | S | | S j | j 

I |.___ _„_^________ __ — + + +~— + -I— —4- 4 

I j tcb location address | | | S j S | I S | | 

!._____ ___J|._ .... __ _____4_____4. + __4._____+ + ^ 

I DELETE I DE= | | | S ] | S | S | | 

I ^___„__ ........ ,4._____+_-___+_ 4.__ 4- 1 1 

I I EP= \ SI J I \ II I 

I y..^ _ ________4. ^+__^__4____-^____-+ 4.- + 4 

I I EPLOC= i I I S I I S I S I I 

L . ^__x . ._ ; -X: X X . :x X X-.^ X J 



I Macro 

I Instruction 



DEQ 



F 

j DETACH 



j. 

I DOM 



Operands 
qname address 



rname address 
rname length 
STEP or SYSTEM 
RET=HAVE 

tcb location address 

STAE= 

MSG= 

MSGLIST= 



j Written as 

|- T T r T 

I I Register | | 

I |. ^ T ^ I A- type 

I Dec I (2- I I |RX- ladcon 

Sym I Dig | 12) | (1) | (0) |type|type 

1. + 

I I S E I I I E I S L 

I I S E I I I E I S L 
+ + + + + + 

S L £|S L E| S £ I I I I 
X X X X X X , 

written as shown 



written as shown 
T T T- 



T T- 

I s I 



YES or NO 

T T" 



DXR 



ENQ 



GETMAIN 



regl 
reg2 



-+ + H 



qname address 
rname address 
E or S 



I S I I 

-+ + +- 

i S I I I i I 
+ + + 1 

I I S E I I I E I S L 



1 i^^i X |E|SL 

written as shown 



rname length 
STEP or SYSTEM 



S L E|S L 
x_- 



— T 

£| S £ 
._X 



written as shown 



FREEMAIN 



RET= 

E, L, R or V 



TEST, USE, or HAVE 



A=(with E, L, or V) 
A=(with R) 



written as shown 
T — 



LA= 

LV=(with £) 
i.V=(with R) 
SP=(with £, L, or V) 



SP=(with R) 

EC, EU, LC, LU, VC, or VU 



— T T r r r 

I I S E I I I E I S L 
+ + + + -+ 

_ _ J ' _^ L ' 

I I S £ I I I E IS L 

S L E|S L £| S E I I I I 

s{s|s| |s| I 

S L £|S L £| S E I I I I 

+ + + 4 ^4. + 

S I S I S 1 I S I I 
X X X ^-J X J 



refer to macro description 



A= 

BNDRY= 



S E i 



I I E I S L 
-X X X 



DBLWD or PAGE 



LA= 

LV=(with E) 



T T r- 

I I S E I 

SLE|SLE| SE| 
— .X X X- 



I I E I S L 
.+ 



-X X. 
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Written as 



Macro I 
Instruction | 

GETMAIN "I 
(cont'd) I- 



GTRACE 



IDENTIFY 



LINK 



LOAD 



PGRLSE 



POST 



RETDRN 



Operands 
LV(witli R) 

SP=(with E, L, br V) 
SP=(with R) 
DATA= 
LNG= 





I I I Register 
I I Y 

I I Dec I (2- I I 

I Sym I Dig ( 12) | (1) | (0) 

I S I S I S I I S 

|S L E|S L E| S B ( I 

^ 

S IS I s I I S 



r^^ 

I 

^ 



H i A- type I 
|RX- ladcbh I 
I type I type | 

-+—--+-—---4 
I I I 

— 

i I i 

-+ — +- -f 



^ + ^ ^ — 

I I I s I I 

-+ + + 

|S L EjS L E|S L h\ \ 



-+ — -+~ — ^ 

I S jS L E I 
-+—-+- —■ f 



FID= 


___ ^ ^ 1 

|S L £|S L £|S L £| 


— + — 
1 


— 1 — -f.— — 
1 1 


ID= 


+- -+——+——+— 

1 S E 1 S £ 1 j 




— +— 
1 

— + — 


— + — + 

1 1 

— +— +— — 



ENTRy= 

EP= 
EPLOC= 
DCB= 
DE= 
EP= 
EPLOC= 
ID= 

PART^ 
VL=1 
DCB= 
DE= 
EP=^ 



+ +— - 

I S I 

+— + 

I I 

+ + 



I S I S 

-+ — -+ — ^- 



-+ +-—- 

|S L E| 



-+ +- 

I s I 

-+ +- 

I S E I 

-+ +- 

I S E I 

-+—--+- 



+ 

I 

+ 

I s 

+ 



-+——+—- 
I S £ I 

■\— +— - 



+ ~+ 

|S E IS £ I I 

I I I S E I 

X -:-± _. 

I written as shown 

-+-~~T- ~ T '—- — T 

I I I s I « 

— 

I I I s I 

4——+ 1— — . 



+ + --f 

I I I 

+ — f ^ 

i s I I 

+ — -i- -I 

I E I S L I 

+ — + ^ 

I E I S L I 
+— — -I 
I I 

f— — ^ 

I S L I 
+ -f 



-+— 
I 

-+— 



I 



I E 
__x 



■+ — 

I s 

-+— - 



-T 

4— 
I s 
4— 



+ ^ 

I s I 

X___ ^ 

I 

T — — ^ 
I 

—i 



4— 
I 

4— — ^ 



EPLOC= 


— +— 

■ 1 ■ 


— + 

1 


— +- 
1 

— +- 


+— 

s 1 

-— — +— 


+- 

t 

— +- 


+- 

s I 

+- 


— + — 

s 1 

+ 


LA= 




1 


1 

— +— 


1 

— +- 


S £ 1 
— — +— 


1 

— +- 


S E 1 




|S L E 

+— — 


HA= 


——i 

— 


1 

---+— 


1 

— +- 


S E 1 S 
+— 


E i 


1 

+- 


jS L E 
+— . 



list addr= 

reg 3= 
ecb address 
completion code 
(regl, reg2) 
T 

RC= 



r 

4— H 



4— +— - 

I I I E I 

4— --+——+— —+—- 
I I I s I s 

+ 

I s I s I s I 

4— +——+——+—- 

I I s I I 

X X -_X — 

I written as shown 

4 -T— 

IS I s 



4 

I 

4 

I 

4 

- 



I E I 

4 +- 



I 
I 

— ^ 



4— 
I 

4— 



1 

I 

^ 

I 

— ^ 



"T 

I or (15) 

-X. — _:_ :.L — - 



-I 
I 

-4 

I 

—J 
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^ Tl 

I Written as | 

I I Register | | 

I I- r r ^ I A- type 

I Dec I (2- I I |RX- jadcon 
Sym I Dig | 12) j (1) | (0) | type | type 
^ 4- + + + + 

I S I i i I i 

X X . i X X X 

written as shovm 



Macro 

Instruction 



Operands 
(regl,reg2) 
T 

identifier name 

external segment name 

DCB= 

ID= 

LIST= 

PDATA 

SDATA 

STORAGE 



SAVE 



SEGWT 
SNAP 



character string or ♦ 

T T T 

S t I i 

+ ^ + 

I I S E I 
+ + + 

S L £|S L £| S E I 
+ + + 

I 





j TCB= 




1 


1 s 

-+— 


E 1 


1 

— + 


SPIE 


1 interruption exit address 


-+— 


— + 

1 


1 s 


+— 

E 1 


1 




1 interruptions 


- X - 


— + 

|S L 


-+— 
E| 


— +— 
1 


--+ 
1 



STATUS 



i £ I S 1 
! I 

-+ + 



i S £ I I I £ I S L 



refer to macro description 



refer to macro description 

T T T T T T 

I I S £ I I I E I S L 

I E I S 



-+ + 

I £ I S L 

-+ + 



STOP or START 
TCB= 

REAL, TASK or WAIT 

timer completion exit addr 

BINTVL= 

DINTVL= 

MIC= 

TOD= 

TUINTVIr= 

DEC or BIN or TU 
MIC 

address 

CANCEL 

TU or MIC 

number of events 

£CB= 

ECBLIST= 

message 



written as shown 

T — • T T r — 

I I s I I 

X_ X X X X 

written as shown 

^ y. T r r 

I I s I I s I 

4. + 4- — + + 

I I s I s I I 

+ -I- + + + 

I s I s I I 



STIMER 



S I 
+- 

S I 
+- 

S I 



+ + (. + + + 

I I S I S I 1^1 

I I S I S I I S I 

1 4- 1 

I I s I 

X X — 

written as shown 



-+- 
I S I 

.X X. 



— +- 

SI 
X, 



TIME 



TTIMER 



WAIT 
WAITR 



written as shown 
~T T- 



JL X 

written as shown 



L_x 



— 

S I 
X. 



written as shown 
S 



WTL 



T T T T T- 

I S I S I I S I 
— + + + 4. 4.. 

I I s I s I I 
I I s I s I I 

X X X X . L- 

any message within apostrophes 



+. 

s I 

— 

s I 
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I 



Macro [ 
Instruction | 



Operands 




Written as | 

T — T T T ^ 

Register | j | 

— T r— ^ I A- type I 

(2- 1 1 |RX- ladGon | 
12) I (1) I (0) I type I type | 
X X x____x 

message within apostrophes 



WTO 



message 



RODTCDB= 



DESC= 
message 
reply address 



|S L 


1 


1 


1 


1 


1 


+ 

|S L 


-+— 
1 


— +— 
1 


1 


— +— 
1 


— + 



WTOR 



length of reply 
ecb address 



ROUTCD^ 
DESC= 



any message within apostrophes 

T T T T — r 

S E I 

-I- 

S E I 

+— - 

S E I 



S L E 



S L E 



S L 
S L 



T- ■ — 

E I S L 
— + 



+ 

E I S L 



XCTL 



(regl,reg2) 



DCB= 



EPLOC= 



HIARCHY= 



S E 



E I S 



S E I 



S L 



S £ 



E I S L 



S L £ 



S £ 



E 1 S L 



S L E 



E I 



E I 
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APPENDIX B; MACRO INSTRUCTIONS 



Explanation of style 

Words in all capitals are coded as shown; appropriate values are 
to be substituted for words in lower case letters. Shaded 
operands may only be used in a VS2 system. Brackets, ( ) , 
enclose operands that may be used or omitted as required; 
stacking within braces, { ) , >s used to Indicate a choice of 
operands or valuos. Underlining, , indicates a default value. 



Footnotes: 

• In full-word on full-word boundary 

In double-word on double-word boundary 
+ Left justified in double-word on byte boundary 
o Multiple of eight; value given in bytes 



LOAD MODULE CONTROL 



Pass control 
and initiate 
execution 

Dynamically 
load and 
initiate 
execution 



Transfer 
control 



Dynamically 
load 



Delete 



Identify 
embedded 
entry point 

Load 

overlay 

segment 



CALL 



LINK 



XCTL 



LOAD 



DELETE 



IDENTIFY 



SEGWT 



entry point name [, (address parameter [, address parameter] ...)[,VL] ] 
l,ID=0 to 65535] 

!EP-entry point name ) 
EPLOC^address of entry point name+ > [,DCB=dcb address] 
DE=address of list entry ) 

[,PARAM=(address parameter [, address parameter] ...) [,VL=1] ] 

(,ID=0 to 65535] 



( EP=entry point name 
[(register (s) 2-12)], < EPLOC=address of entry point name+ 
( DE=address of list entry 

[,DCB=dcb address] 
EP= entry point name 

EPLOC=address bf entry point name+ } [,DCB=dcb address] 
DE=address of list entry 



!EP=entry point name 
EPLOC^address of entry point name"*" 
DE^address of list entry 



( EP=entry point name ) ,ENTRY=entry point address 



( EPLOC=address of entry point name+ 1 



external segment name 
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SYNCHRONIZATION 



Wait for 
event 



WAIT 



[number of events,] S ECB=ecb address 



ECBLIST-address of list of ecb addresses* 



Wait for event 
while lower 
priority task 
is executed 



WAITR 



[number of events,] \ ECB=ecb address 



ECBLIST=address of list of ecb addresses* 



Post event 
completion 

Request 
control of 
serially 
reusable 
resource 



Release 
serially 
reusable 
resource 



Set interval 
timer 



POST 



ENQ 



DEQ 



STIMER 



ecb address [,0to 16,777,215] 



(qname address,rname address,j^^J, [rname length] ,pSYSTEM1 ,...) 



LSTEP J 



,RET=TEST 
,RET=USE 
.RET=HAVE 
L,RET=CHNGJ 



(qname address,rname address, [rname length] ,rSTEP T..,) 
l.RET=HAVEl "-S^^^J 



E means exclusive control J j^^^^i^ g 
S means shared control J 

SYSTEM means resource used by more than one job 
STEP means resource used by issuing job 



REAL, [address of interval end routine] 
TASK, [address of interval end routine] 
WAIT 



Test interval 
timer 



TTIIVIER 



,D I NTV L=address of decimal interval * * 
,B1NTVL- address of binary interval in seconds* 
,TUINTVL=address of binary interval in timer units* 
,TOD=address of time-of-day of interval end** 



[CANCEL] I. ITU 



< M|C,adl(lNr0M 



TIME AND TIME INTERVALS FOR TIME, TTIMER, AND STIMER 



Decimal (DEC and DINTVL operands): 

Eight packed decimal digits in format HHMMSSth 
HH = hours In 24-hour clock 
MM = minutes 
SB - seconds 
t = tenths of seconds 
h = hundredths of seconds 



Binary in seconds (BIN or BINTVL operands): 

Unsigned 32-bit binary number in a full-word on full-word 
boi^nd^ry; least significant bit has a value of 0.01 second 

Binary in timer units (TU or TU I NTV L operands): 

Unsigned 32-bit binary number in a full-word on full-word 
boundary; least significant bit has a value of 1 timer unit 
(1 timer unit = 26 micro-seconds) 

Binary in microseconds (MIC operand): 

Unsigned 64-bit binary number in a double-word on a 
double-word boundary. Bit 51 is the low order digit of 
the interval value. 
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PROGRAM INTERRUPTION CONTROL 



l:;n.il)le iiiul SPIF: | iiitorriiplioii exit routine! addn.'ssl 

disable 

program I, (interruption type l,interruptlon typej ...)] 

interruptions 

and transfer 

control to 
interruption 
exit routine 



INTERRUPTION TYPES FOR SPIE 



Type 


Meaning 


Maskable 


Type 


Meaning 


Maskable 


Type 


Meaning 


Maskable 


1 


Operation 


No 


6 


Specification 


No 


11 


Decimal divide 


No 


2 


Privileged operation 


No 


7 


Data 


No 


12 


Exponent overflow 


No 


3 


Execute 


No 


8 


Fixed-point overflow 


Yes 


13 


Exponent underflow 


Yes 


4 


Protection 


No 


9 


Fixed-point divide 


No 


14 


Significance 


Yes 


5 


Addressing 


No 


10 


Decimal overflow 


Yes 


15 


Floating-point divide 


No 



— 



CONTROL BLOCKS 



Evctu contiol bkn.k (f CB): 
0 12 31 lifts 



W 



POST CODE 



W =- wait flag 

C - completion flag 



Progmni inteiruptioii control aiea (PICA): 

0 1 2 3 4 5 bytes 



I pro- 
0000 I gram 
I mask 



exit routine 
address 



interruption 
mask 



Program interruption element (PIE): 
0 1 2 3 bytes 



0 




PICA address 


4 


Old Program Status Word 


8 


after 


nterruption 


12 


Register 14 


16 


Register 15 


20 


Register 0 


24 


Register 1 


28 


Register 2 


bytes 







Appendix B: Macro Instructions 191 



GENERAL SERVICES 



Delete 
nnessage(s) 
from 
display 

Write to 
operator 



Write to 
operator 

and wait 
for reply 

Write to 
log 

Divide 
extended 
precision 
floating 
point numbers 

Get time 
and date 



DOM 



WTO 



WTOR 



WTL 



DXR 



{MSG^register containing 24-bit, right-justified message number 
MSGL.IST==address of list of futlwords, each a 24-bit, right-justified 
identification number of message to be deleted 



'message' I, ROUTCDE={number [.number] ,...)] 
I 'message* > 
< ('text' [,line type] ), . . . I 

[DESC=message descriptor cod|e(s)] 

'message'.address of reply area.length of reply.eeb address 

[,ROUTCDE»=(number [,number] ,...)] t,DESC=message descriptor code(s)] 

'message' 

register containing dividend.register containing divisor 



Only registers 0 and 4 can be used; 
they may be specified in either order. 



TIME 



DEC 
BIN 
TU 

.MIC,address _ 



TIME AND TIME INTERVALS FOR TIME, TTIMER, AND STiMER 



Decimal (DEC and DINTVL operands); 

Eight packed decimal digits in format HHMMSSth 
HH = hours in 24-hour clock 
MM = minutes 
SS = seconds 
t = tenths of seconds 
h = hundredths of seconds 



Binary in seconds (BIN or BINTVL operands): 

Unsigned 32-bit binary number in a full-word on full- 
word boundary; least sigriificant bit has a value of 
O.Ol second 

Binary in timer units (TU or TUINTVL operands): 

Unsigned 32-;bit binary number in a full-word on full- 
word boundary; least significant bit has a value of 1 
tinier unit (1 tirnier unit = 26 micro-seconds) 

Binary in microseconds (MIC operand) : 

Unsigned 64-bit binary number in a double-word on a 
double-word boundary. Bit 51 is the low order digit 
of the interval value. 



Save 

register 

contents 



SAVE 



(register(s) 14 through 12) l,T] [.identifier] 



In SAVE, T means: save 
registers 14 and 15. 
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GENERAL SERVICES 



Du mp 

StOtiUjO 

iiiul contiimi; 



SNAP 



Record 
traco data 



GTRACE 



TERMINATION 



DCB address of data control block | ,TCB address of TCB address* 
1,ID 1 to 1271 



[,SDATA-( ^ TBI 



. ALL i 
\ NUC/ 

[ TBI • 



,ALL 

.NUC 

,TRT 

,CB 

,Q 



/ ALL 
\ PSW 
J REG 



GS 

,PDATA ( \ SA or SAH 

j JPA or LPA or ALLPA 
fsPLS 



,ALL 

,PSW 

,REGS 

,SA or ,SAH 

,JPA or ,LPA or ,ALLPA 
,SPLS 



...)J 



SNAP 


SDATA VALUES 


ALL 


of titi; following fiolds 


NUC 


till of tuicleus except trace tal)l(; 


TRT 


tiiice table 


CB 


TCB, active RBs, JPACQ, and MSS control blocks 


SNAP 


PDATA VALUES 



ALL ill! of itie following fields (assume SA and ALLPA) 

PSW Pi o()ram Status Word when SNAP was issued 

REGS contents of general registers when SNAP was issued 

SA linkagi? infoimation and back trace 

SAH linkagi? miormation only 

JPA all viitual storage assigned to jol) step 

LPA contents ol resident reenterable load module 

ALLPA - JPA I LPA 

SPLS contents of virtual storage subpools 0 -127 



[.STORAGE - (starting address, ending address, . . . ) j 
,LIST address of list J 
DATA address.LNG-nunnber of bytes of data.lD-record ID 

I, FID format identifier routinel 



Terminate 
normally 



Tiirminate 
ahnornrtariy 



REIURN 



[(register(s) 14 through 12)1 (Jl f LRC-0 to 4095 M 

L?,RC (15) U 



In f^fc'rUI-iN, T mciins: plac(! all ones 
ID Ingh oidci bvK' ol sav(.> area woid 4. 



ABEND 



0 to 4095. [DUMPI I, STEP) 
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TASK CONTROL 



Dynamically 
load and 
initiate 
execution 



ATTACH 



EP entry point name 

EPLOC address of entry point name+ } l.DCB -deb address] 
DE~address ol^ name field of list entry 



[,PARAM^ (address parameter [.address parameter! ...) [,VL 1] ] 

[.ECB^^ecb address] l.ETXR address of routine to be entered when] 

subtask terminates 

[.LPMOD=-^number subtracted from limit priority] 

[.PPMOP -signed number algebraically added to dispatchiny priority 1 



Delete 



Change 
priority 



Change 
subtask 
dt^dtchibitity 



DETACH 



CHAP 



STATUS 



[,TQE (YES) 
<N0 » 



.FPREGSA- « YES) I 
< NO ) 



VS1 only 



[,G$py«number l f, 
,GSPL»addrfess of list J 



SH§PV=number 
Sf<SPL«addreW of I 



ist j 



l,SZERO= t YES I ] (.TASKLIB-dcb address] 

[.STAI=(exit address [.parameter list address] )] 

I YES) 
two ) 



LPURGE« ( NONE 
^HALT 
(QUIESCE 



] l,ASYNCH« j YES r] 
NO 



address of tcb address * [,STAE= \ YES I ] 



signed number to be algebraically added to tlispatching priority 



[.address of tcb address"! 
:i J 



'S' indicates that thi; priority of the 
HctivH task is to l)R chaniiurl. 



t START \ (,TCB»address of subtask tcb address) 
* STOP ■ ■ 



19M 



VIRTUAL STORAGE ALLOCATION 



Allocate 
storage 



GETMAIN 



R,LV-lengtho (,SP-Oto 127] 



GETMAIN 



/ \ECLLV-lengtho 
I /Eu{ 

) i VC J ,LA=address of lengtho list 




,A=adclress of specif ication list 



I ( LC ) ,tA«addre$s 
\ (LUf 



[,SP=0to127] [,BNDRY= / dBLWd \ 

( PAGE / 



Release 
storage 



FREEMAIN 



R,LV=lengtho,A=address of storage area address* list [,SP=0 to 127] 



FREEMAIN 




MODE OPERANDS FOR GETMAIN AND FREEMAIN 

R=register type 

E=single area, fixed length 

V=single area, variable length 

L-virtual area(s), variable length(s) 

U=unconditional 

C=conditional 



Release PGRLSE LA=low address of area,HA=high address+1 of area 



virtual 
storage 
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APPENDIX C; MESSAGE ROUTING FOR MULTIPLE OPERATOR CONSOLES 



ROUTING CODES 

Routing codes provide the mechanism to route WTO and WTOR messages to 
the locations where they are needed. They indicate the functional area 
or areas to which a message is to be sent. If no routing code is 
assigned, default is to routing as if Kaster Console Information. These 
codes are not printed or displayed as part of the iTiessage text. To use 
routing codes effectively, the system irust have the Multiple Console 
Support (MCS) option included at system generation. Without the MCS 
option, all routing codes are assigned to the one active console, except 
when routing code 11 is used to obtain a Write-to-Prograninier message in 
the message output class. 

Routing codes and their definitions are: 

Code Description 

1 MASTER CONSOLE. This routing code is for messages that must be 
sent to the master console because some action is required by the 
master console operator, or because the message contains informa- 
tion considered critical to the continued operation of the sys- 
tem- Keep the number of messages with this attribute to a 
minimum. 

2 MASTER CONSOLE INFORMATIONAL. This routing code is for informa- 
tional messages to the master console operator. Informational 
messages usually require no action from the operator. If they 
do, that action should be at the operator's discretion. 

3 TAPE POOL. See routing code 4. 

4 DIRECT ACCESS POOL. The tape pool and direct access pool routing 
codes are for messages that contain instructions for volume 
handling in the tape and disk areas. Messages about error condi- 
tions which occur as a result of the operation of these devices 
may also be assigned one of these routing codes. 

5 TAPE LIBRARY. See routing code 6. 

6 DISK LIBRARY. The tape library and disk library routing codes 
are used for any message that specifies tape library information 
or disk library information. 

7 UNIT RECORD POOL. This routing code is for messages about prin- 
ters, punches, and card readers. Send the following classes of 
information to this pool: 

• Types of printer chains or trains required. 

• Carriage control tapes required. 

• Types of forms or cards required - 

• Error conditions on unit record equipment. 

8 TELEPROCESSING CONTROL. Use this routing code for messages 
relating to teleprocessing. 

9 SYSTEM SECURITY. Use this routing code for messages of interest 
to the system security office (such as password messages) . 
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10 SYSTEM/ERROR MAINTENANCE. Use this routing code for any message 
indicating system errors or incorrectable I/O errors, and for any 
message associated with system maintenance. 

11 PROGRAMMER INFORMATION. Use this routing code for messages of 
interest to the programmer. The message is included in the mes- 
sage class for the job and written on the system output device- 

12 EMULATOR INFORMATION. This routing is for messages issued by an 
eitiulator program. 

13 USER ROUTING CODE. Available for customer usage - 

14 USER ROUTING CODE. Available for customer usage. 

15 USER ROUTING CODE. Available for customer usage. 

16 RESERVED FOR FUTURE USE. 

DESCRIPTOR CODES 

Descriptor codes functionally classify WTO and WTOR messages so that 
they inay be properly presented on all consoles and deleted from display 
type consoles. Each WTO and WTOR message should contain orie descriptoi: 
code. If no descriptor code is coded in the WTO or WTOR, no descriptor 
code is assumed. Descriptor codes 1 through 7 are mutually exclusive . 
Descriptor codes 8 and 9, however, may be used with any other descriptor 
code. These codes are not printed or displayed as part of the message 
text. To use descriptor codes (except codes 1 and 2), the system roust 
have the Multiple Console Support (MCS) option included at system 
generation. 

Descriptor codes and their definitions are; 

Code Description 

1 SYSTEM FAILURE. This descriptor code is for messages that indic- 
ate that a catastrophic error has occurred and another IPX of the 
system is required. 

2 IMMEDIATE ACTION REQUIRED. This descriptor code is for messages 
that request an immediate operator action (completion of the 
action is required before a task can proceed) . Messages with 
descriptor code 2 must be deleted by a Delete Operator Message 
(DOM) macro instruction w^eh the operatbr action has been accomp- 
lishedf or the operator will hAve to perform the action to delete 
the messages. 

3 EVENTUAL ACTION REQUIRED. This descriptor code is for messages 
requesting operator action where a task does not await completion 
of the action. 

U SYSTEM STATUS. This descriptor code is for messages that indic- 
ate the status of the system, such as system task status or a 
hardware unit status such as uncorrectable I/O errors. 

5 IMMEDIATE COMMAND RESPONSE. This descriptor code is for error 
and nonerror messages that are written as a direct result of an 
operator or system Command. 

6 JOB STATUS. This descriptor code is for messages that indicate 
the status of a job or job step. 
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7 APPLICATION PROGRAM/PROCESSOR. This descriptor code is for mes- 
sages issued by problein prograirs or by processors executed as 
probl«?nn programs. This descriptor code is the End-of-Step mes- 
sage deletion indicator, and all messages with this code are 
deleted when the job step in which they were issued is 
terminated. 

8 OUT-OF-LINE MESSAGE. This descriptor code is used for one mes- 
sage or a group of one or more messages that is to be displayed 
out of line. If the device support cannot print a message out of 
line, the code will be ignored and the message will be printed in 
line with other messages. 

9 RESPONSE TO OPERATOR REQUEST (MLWTO) . This code specifies that 

the multiple line message is a response to an operator's request 
for information via the DISPLAY or MONITOR command- Specifying 
code 9 with a multiple line WTO will cause an MLWTO identifica- 
tion number to be put in the control line of the message so that 
the message may be canceled. If a control line does not exist, 
the system will provide one as follows: 

IEE932I nnn 

where nnn is the identification number. 
10-16 RESERVED FOR FUTURE USE. 



O PERANDS FOR USE BY THE SYSTEM PROGRAMMER (VSl) 

For a description of the system programmer WTO operands in VS2, see 
the publication 0S/VS2 Planning and Use Guide . 

The WTO and WTOR macro instructions have two special operands, the 
MSGTYP and MCSFLAG operands. These operands should be used only by the 
system programmer who is thoroughly familiar with the Multiple Console 
Support (MCS) Communications Task, since improper use of these operands 
can impede the entire message routing scheme. These operands set flags 
to indicate that certain system functions must be performed, or that a 
certain type of information is being presented by the WTO or WTOR. 

The MSGTYP and MCSFLAG operands may be specified on either the stan- 
dard or list form of the WTO and WTOR macro instruction. The standard 
form of the WTO macro instruction is shown below. 



—r T 






(symbol! | WTO | T message' 




\ 


1 1 U 'text' (, line type]),,.,) 


1 1 [,ROUTCDE= 


=(number(, number] ,,..) ] 


1 1 [ ,DESC=number] 




1 1 


N 




1 1 [ ,MSGTYP= 


Y 


] 




JOBNAMES 






STATUS 






ACTIVE 




1 1 [,MCSFLAG= 


= (name (, name, ..] ) 









' message* 

specifies that the message text is to be placed between the first 
and second apostrophes. 



I ] in(^icates optional name or operand; select one from vertical stack 
within { > . 
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ROUTCDE= 

specifies the routing codes to be assigned to the message. 



DEsc= ; 

specifies the descriptor codes to be assigned to the message. 

MSGTYP=JOBNAMES or MSGTYP= STATUS 

specifies that the message is to be routed to the console which 
issued the DISPLAY JOBNAMES or pi SPLAY STATUS comroand, respective- 
ly. When the message type is identified by the operating system, 
the message will be routed to onl^ those consoles that had 
requested the information. Omission of the MSGTYP parameter causes 
the message to be routed as specified in the ROUTCDE parameter. 

MSGTYP= ACTIVE 

specifies that the multiple-line message is in response to a MON- 
ITOR A (MN A) command and should be routed to the console that 
issued the command , 

MSGTYP=Y or MSGTYP=N 

specifies that two bytes are to be reserved in the WTO or WTOR 
macro expansion so that flags can be set to describe what MSGTYr 
functions are desired. Y specifies that two bytes of zeros are to 
be included in the macro expansion at displacement WTO + 4 + the 
total length of the message text, descriptor code, and routing code 
fields. N, or omission of the MSGTYP parameter, specifies that the 
two bytes are not needed, and that the message is to be routed as 
specified in the ROUTCDE parameter. If an invalid MSGTYP value is 
encountered, a value of N is assumed, and a diagnostic message is 
produced (severity code of 8), 

When MSGTYP=Y, the issuer of the WTO or WTOR macro instruction that 
contains the MSGTYP information must set the appropriate message 
identifier bit in the MSGTYP field of the macro expansion (see 
Figure 60). Prior to executing the WTO or WTOR SVC (SVC 35), he 
must also set byte 0 of the MCSFLAG field in the macro expansion to 
a value of X'lO'. This value indicates that the MSGTYP field is to 
be used for the message routing criteria. When the message type is 
identified by the system, the message is routed to all consoles 
that had requested that particular type of information. Routing 
codes, if present, are ignored. 



I Bit I Meaning j 
^ ^ _____ 

I 0 I DISPLAY JOBNAMES | 
^ _+ _ f 

I 1 I DISPLAY STATUS j 
y ^ _ _________^ 

I 2-15 1 Reserved for system use. j 
1 I Must be zeros. j 

L_. , i . , .___ _ .__J- ■ 

Figure 60. Bit definition for MSGTYP=Y 
MCSFLAG 

specifies that the macro expansion should set bits in the MCSFLAG 
field as indicated by each name ceded. Names and their correspond- 
ing bit settings are shown in Figure 61- 

ROUTCDE, DESC, and MSGTYP parameter combinations are shown in Figure 
62. coding of any one of the four keyword parameters (ROUTCDE, DESC, 
MSGTYP, MCSFLAG) causes a new format WTO or WTOR to be generated. 
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NS ItlG 


1 


Bit 












A 

\j 








REGO 


i 


1 




Message is to be queued to the console 




RESP 




2 




The WTO is an iirimediate command response. 









3 


1 






REPLY 




^ 


1 


The WTO macro instruction is a reply to a 
WTOR macro instruction 




BRDCST 




5 


1 


Message should be broadcast to all active 
consoles. 




HRDCPY 


1 


6 


1 


Message queued for hard copy only. 




OREGO 




7 


1 
1 


Message is to be queued unconditionally to 
the console whose source ID is passed in 
Register 0. 




NOTIME 


1 


8 


1 


Time is not appended to the message. 








9 




MLWTO indicator. 








10-12 


-+- 






NOCPY 




13 




Protect key 0 user only. 








14-15 


1 






Note: Invalid specifications are iqnored and produce an 
appropriate error message. 



Figure 61. MCSFLAG parameters 
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Parameter Coded 



-TT- 
II 

T T T f f- 

ROUTCDE I DESC | MSGTYP | MCSFLAG | | 

-f+- 



bxpansiion tJeiiotdtt^;; 



CFSJC 



j MSGTYP 



MCSFLAG 



Specified 
Specified 
Specified 
Specified 
Specified 

Specified 
Specified 

Specified 
Specified 
Specified 



Specified 
Specified 
Specified 
Specified 
Specified 

Omitted 
Omitted 
Omitted 
Omitted 
Omitted 



JOBNAMES 
STATUS 
Omitted 

If 
N 

JOBNAMES 
STATUS 
Omitted 



Optional 
Optional 
Optional 
Optional 
Optional 

Optional 
Optional 
Optional 
Optional 
Optional 



I I Codes 
i 1 Codea 

I I Codes 

I I Codes 
j I Codes 

-+f 

1 1 Codes 
I I Codes 
I I Codes 
I I Codes 
1 icode:; 
-H- 



Specif ied I Codes Specified | Zeros 
Specif ied I codes Specif ied | Kiel (i Omitt 
Specif ied I Codes Specified! X*8000' 
Specif ied I Codes Specif ied| XV«»000' 
Specif ied I Codes Specif ied | field Omitt 



+- 

Specif ied | 
Specif iedj 
Specit ied | 
Speci f ied 1 
r.pecif iedj 



. Zeros 
Zeros 

'Zt.'roK 
Zeros 
Zero;; 



+— 

I Zeros 
ll'ield Omitt 
I X'ttOOO" 
I X'MOOO* 
I F i e J (1 i t t 



IRS 
ed I As 
|As 
I As 
ed | As 

— +— 
I As 
ed I As 
I As 
I As 
..riJAs 
-- + — 



i'lpecif iedtt 
Specifit'dtt 
Specif iedtt 
Specif ied# 
Specified* 

Specif iedtt 
Specif iedtt 
Specif iedtt 
;;pecii iedtt 
Speci t i cdV 



Omitted 
Omitted 
Omitted 
Omitted 
Omitted 



Specified 
Specified 
Specified 
Specified 
Specified 



johname;; 

STATUS 
Omitted 



Omitted* | | Routine) co<it> 2 jtroii*':: ;;|.< ci t i <><i | Zi io:. 

Omitted* || K<>ut inq C<5de 2 jcocloji :!p«><:i t i«>cl | l'i<' Id Omi it . 

(Jinitted* ||l<outin<) Code 2 jcodou Sp<ciliod| X'8000' 

Omitted* | | Routing code 2 | Codes .'ipeci Hod j X' UOOO ' 

Omitted* IIRouting Code 2 jcodes S{)ecif iedj KielU omitte 



<1| 



X ■ 11000 • 
X' tiOOO* 
X'8000' 

X' aooo' 

X' 8000' 



++- 

RtGO/QREGO| 1 
REGO/gREGO | i 
REGO/gREGOj i 
REGO/QREGO | j 
REGO/CREGO I I 



Omitted 
Omitted 
Omitted 
Omitted 
Omitted 



Specified 
Specified 
Specified 
Specified 
Specified; 



Y 

N 

JOBNAMES 
STATUS 
Offltted 



Zeros |Ctjdfs Specified | Zi-ros |As i;p»-ci f iedtt 

Zeros i Codes Speci t i<>d | 1-M ei d Oiiii t t id j As Specit iedtt 

Zeros jcodes Specified! X'8000' jAs Specifiedit 

Zeros jcodes Specitied| X'4000' jAs Specif iedtt 

Zeros [Codes Specif ied j Field Omitted|As Specified* 



— ++ — — 

Omitted* | | Routing Code 2 | Zeros | Zeros 

Omitted* j| Routing Code 2 j Zeros jfield Omitte 

Omitted* HRouting Code 2 j Zeros | X'8000' 

Omitted* | j Routing Code 2 j Zeros | X'1000' 

Omitted* I I t'ield Omitted j Field Omitted | Field Omitt e 



Omitted 
Omitted 
Omitted 
Omitted 
Omitted 



Omitted 
Omitted 
Omitted 
Omitted 
Omitted 



JOBNAMES 
STATUS 
Omitted 



-++- 



X' 8000" 
X'8000' 
X' 8000' 
X'8000' 

Zeros 



Omitted 
Omitted 

Omitted 
Omitted 
Omitted 



Omitted 
Omitted 

Omitted 
Omitted 
Omitted 



Y 
N 

JOBNAMES 
STATUS 
Omitted 



REGO/QREGO | | Zeros 

REGO/QREGOII Zeros 

REGO/QREGO j j Zeros 

REGO/CREGOII Zeros 

REGO/gREGO|| Zeros 



Zeros 
Zeros 
Zeros 
Zeros 
Zeros 



I Zeros 

i Field Oirdtte 

I X'SOOO' 

I X'UOOO' 

I Field Omitte 



I As Specif iedtt 
d|As Specifiedtt 
I As Specifiedtt 
|As Specifiedtt 
d|As Specifiedtt 



* If an MCSFLAG other than REGO or QREGO is specified, the expansion genera 
that the MCSFLAG field contains the MCSFLAG specified and the high-order 

# High order bit set to 1 to indicate a new format m<)cro expansion (routing 
fields exist). 



tes the same fields except 
bit set to 1. 
code and descriptor code 



Figure 62. ROUTCDE, DESC, and MSGTYP combinat ions 
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INDEX 



Indexes to systems reference nanuals are 
consolidated in O S/VS Mas t er Index , GC28- 
0602. For additional inforniation about any 
subject listed below, refer to other publi- 
cations listed for the same subject in the 
master index. 



A-type ADCON 79 
ABEND 82,83 

use of as 
abnormal condition handling 47-50 
abnormal termination 49-51,82 

control program functions 49,50 

dump 50,51 

job step not terminated 50 

job step terminated 50 
abnormally terminate a task (ABEND) 83 
active task 12 
ADCON 79 

add an entry point (IDENTIFY) 126 
additional entry points 37 
alias names 

in ATTACH 84,87 

in LINK 127 

in LOAD 132 

in XCTL 178 
allocate main storage (GETMAIN) 117 
allocation of virtual storage 117 
answer area 21 

asynchronous exit routines (see exit 
routines) 

asynchronous interrupt processing (see 

interrupt processing) 
ATLAS (see Planning and Use Guide ) 
ATTACH 

execute form 9 2,93 
list form 91 
standard form 84,87 
with CALL 96 
with DETACH 104,105 
with IDENTIFY 84,87,126 
use of 10-12, 15 
avoiding interlock 43,44 



BLDL macro instruction 

with ATTACH 84,87 

with LINK 127 

with LOAD 132 

use of 28, 31, 32 
l)Oundary, page 9 

bring load module into virtual storage 

(LOAD) 132 
BS AM, with SNAP 140 
BTAM, with ECB 159 



CALL 

execute form 97 
list form 96 
standard form 94,95 



use of 21, 22, 33 
called program 3 
calling program 3 
CANCEL, with TTIMER 156 
CATALOG (see Planning and Use Guide ) 
cathode-ray tube display 75 
change dispatching priority (CHAP) 98 
change subtask status (STATUS) 150 
CHAP 98 

use of 12 
characteristics, summary of VS2 2 
CIRB (see Planning and Use Guide ) 
code 

completion 

in ABEND 82 
in ATTACH 85 
in ECB operand 85 
in POST 136 
descriptor 72 
return 7,8 

from DELETE 99 
from DEQ 101 
in ECB operand 85 
from ENQ 108 
from GETKAIN 118 
from IDENTIFY 126 
from SNAP 140 
routing 72 
coding aids 78 
communications 

subtask 16.1,16.2 
task 16.1,16.2 
completion code (see code) 
conditional requests 
from DEQ 100 
from ENg 108 
from GETNAIN 117 

to release resource control 100 
for resource control 108 
fcr virtual storage 117 
console, operator's 71,72 
continuation lines 79 
control 

exclusive 40 
passing of 

with ATTACH 84,87 

with CALL 94 

with LINK 127 

with XCTL 178 
releasing of, with DELETE 99 
requesting of, with ENQ 108 

after ATTACH 84, 87 

after CALL 94 

after LINK 127 
returning, with RETURN 22,137 
shared requests for 40 
conventions 

linkage 3,18 
system 18 
count, responsibility 60-62 
decreasing, with DELETE 99 
increasing, with LOAD 132 
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create a new task with ATTACH 84,87 
creating a subpool 58 
CRT display 75 

CVT (see Planning and Use Guide) 



data control block 

with LOAD 132 

with SNAP lt»0 
data definition (see DE statement) 
date and time 63,154 
DCB 

with LOAD 132 

with SNAP 140 
DD Statement 

with GTRACE 122 

with SNAP 140 

SYS ABEND 84 

SYSDDUMP 84 
DEC DIG 79 
DELETE 99 

with LOAD 132 

use of 60,62 
delete 

operator message 106 

subtask 104,105 
deletion of messages 75 
DEQ 

execute forin 102 

list form 103 

standard form 100 

use of 41-43 
descriptor codes 72 
design technigues 8,9 
DETACH 104,105 

use of 15 
dispatching priority 10-15 

with ATTACH 8 4,87 

with CHAP 98 
divide extended register (DXR) 107 
DOM 106 

use of 75 
DPRTY parameter 11 
dump 

with ABEND 50,51,82 

abnormal termination 50,51 

indicative 51 

with SNAP ,50,51 

SVC 50,51 
dump virtual storage and continue 

(SNAP) 140 
dumping services 50 
duplicate names 10 
DXR 107 

use of 65-71 
Dynamic Dispatching 2 

VSl 12 

VS2 14,15 
Dynamic structure 17 



ENQ 

execute form 112 
list form 111 
standard form lOH-110 
use of 33, 41-43 
bNTRY instruction 20 
entry naire on tXJiC statonient 2') 
entry points 

additional 37,126 
in IDENTIFY 126 
in LINK 127 
in LOAD 132 
in XCTL 178 
calling seguence identifiers 17 
name 

in ATTACH 84 , 87 

in CALL 94 

in DELETE 99 

in IDENTIFY 126 

in LINK 127 

in LOAD 132 

in SEGWT 139 

in XCTL 178 
EOV (see I^lanni ng and jJse Cu 
event completicr) 136 

event control I: lock (ECV) U!,1'>8,1S9 
with Ani'NC 82 
with /\TTAC1I IS, 1(),H') 
with 1'();;t lib 
with WAIT 1'>B , l')9 
exclusive reference 108 
exclusive requests 40 
EXEC statement 3,4 
PARN field of 3 ,4 
with STIiVlER 152 
execute form of iracro instruction 60 
execution 

parallel 18 
serial 18 
existing copy 

use of 28, 30 
exit routines 
asynchronous 

with CALL 94 
with IDENTIFY 126 
with SEGWT 139 
end-of-task (ETXR) 
with AEEND 82 
with ATTACH 85 
With SPIE 145-147 
extended-preciiiion t loat inij-})oiiit 

simulrition 65-70 
ISXTRACT (see Planning and Use Guid e) 



FREEMAIN 113-116 
execute forir ll6 
list form 115 
standard form 113 , 114 
use of 53, 55 



ECB (see event control block) 
efficient design for paging, technigues 
for 8 

emulator message routing 198 
end-of-task exit routines (see exit 
routines) 



generalized trace facility 75,76,122 
GETMAIN 117-121 

execute form 121 

list form 120 

standard form 117,118 

use of 53j54 
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c;T1'' 7'>,122 
GTRACK 122-12') 

execute form 1.21) 

list form 12a 

standard toriri 122,121 

U!_je of 7'), 7b 



l)<jtd-co{>y loq , writiiKj to 7 1,71 



identification nuraher, roeasage 72 
identifier, calling aequence 

in CALL 94 
IDENTIFY 126 

with ATTACH 84,87,126 

with LINK 126 

with LOAD 126 

with XCTL 126 

use of 37 
indicative duirp 51 
interlock condition 43,44 

avoiding 43,44 
interrupt proceui; i n<) 4'j 

asynchronous 

with ATTACJl 8 4, 87 

masking 

with SVlh 145 
with XCTL 178 

typeis 146 
interval timer 63,64 

set 151 

test 156 



JOB statement 

with CHAP 98 
job step 10 
job step task 10 
job step termination 82 



libraries 25,26 

job 25 

link 25 

privat e 25, 26 

step 25 
limit priority 10-12 

with ATTACH 86 

with CHAP <)8 
LJNK 127-131 

wit h t:ALL fii 

ext^cut e form 130,131 

with IDENTIFY 126 

lis*-, form 129 

rc'sponsibility count with 29,30 
standard form 127,128 
use of 10,31, 32 
linkage editor 17 

list form of macro instructions 60 
LOAD 132 

with DELETE 99 

with IDENTIFY 126 

use of 30, 31 
load module 17 

characteristics 17 

execution 

with ATTACH 84,87 



with CALL 94 

with LINK 127 
namts 18 
structures 17 

dynamic 17 

planned overlay 17 

simple 17 

load overlay segment and wait (SEGWT) 139 

loa(iing registers 19 

log 

hard-copy 73,74 
systeir 74,75 
with WTL 161 
with WTOR 174 



macro formats 78 
iracrc instructions 
execute form 60 
list form 60 
aasking program interruptions 
with SPIE 145 
with XCTL 178 
master console information 197 
^C13 (see multiple console support) 
MCSFLAG 199-201 
neirfcer name 

in ATTACH 84,87 
in LINK 127 
in LOAD 132 
in XCTL 178 
message 

action 72 

with WTO 164,168,169 
with WTOP 173,174 
deletion 75 
routing 72,197,198 
to log 161 
tc operator 71,72 
with DOM 106 
with reply 72 
with WTL 161 
with WTO 164-172 
with WTOR 173-177 
tc prcgrairmer 73 
with DON 106 
with WTL 161 
with WTO 164,168,169 
with WTOR 173,174 
microseconds, time of day returned in 63 
niniirizing paging 8 

NODESET (see Planning and Use Guide ) 
rrodule 

reenterable 33 

serially reusable 33 
ySGCLASS parameter of JOB statement 73 
NSGTYP 199-201 

multiple console support (MCS) 72,197 
routing codes 72,197,198 
with WTO 168,169 
with WTOR 174 



new line control character 72 

with WTO 164,168,169 

with WTOR 173, 174 
nonoverlay segment 94 
non-reenterafcle load modules 61,62 
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old program status word (OPSW) Hb,Hl 

OPEN, with SNAP 46,47,140 

operands 

for system programmers 199-201 

summary 183^188 
operator message 71,72 

with DOM 106 

with reply 72 

with WTL 161 

with WTO 164,168,169 

with WTOR 173, 174 
OPSW 46,47, 146 
options, control program 2 
originating task 10,84,87 
overlay segment 94 

with CALL 94 

with SEGWT 139 
owned subpools 57 



pack, job 25 
page 8 

page boundary 9 

paging 8 

paging rate 8 

parallel execution 10,18 

parameter 

list 7,8,21 
passing 19,21 

with ATTACH 8 4, 87 

with CALL 94 

with LINK 127 
partition 14 

passing control 7,8,18-36 

with CALL 94 

called program 7,8 

calling program 7,8 

conventions 7,8 

in a dynamic structure 25-36 

with return 19,2 0 

without return 18,19 

in a simple structure 18-23 
PGRSLE 133-135 

execute form 135 

list form 134 

standard form 133 

use of 55 
PICA 45,46 
PIE 46,146 
POINT, use of 56 
POST 136 

use of 38 

with WAIT 157 
predecessor task 14,15 
priority 

actual 10 

altering 11,12 

dispatching 10,11 

with ATTACH 84,87 
with CHAP 98 

job 11 

job step task 11 
limit 10-12 

with ATTACH 84,87 
with CHAP 98 
task 10-12 
problem program parameter litst 77 
program interruption 



control 45 

contrcl area 45,46 

element 46 

t yi t.'t: 4'), 46 
pro(jramni<'r nies;:-.ficjt> 73 

with WTO 164,168,169 

with WTOR 173,174 
prcqrarrmer rtiesGaqe routing 198 
provi(Je time ami (iate (TIME) 154 
proviciinq a save area 6,7 
I'UKcn- (set- Pl^lIlIiil>il_iL0J_iJl2i:_<ii>i»Ji'^ 

qname rname? lint 41,108 

real storage 8 

real time interval 151 

record, trace data 122,75 

reenterable 

lead irodules 56 

macro instructions 56 

modules 30, 3 3 
registers 

base L) 

calling program 4 
general 3 
linkage 3 
paramet t r 4 
restorirui h 
i;avin<) 4-H, 1 \H 

resource, wit h Dl-.Q 100 

storage, with KKKEMA IN 11 J 

storage, with PCHLSI- 1J3 
relinquish control ot a load nicduie 

(DELETE) 99 
reply, operator's 72,173,174 
request 

conditional (see corjditional requests) 

resource, with ENQ 108 

storage, with GETMAIN ll7 
RESERVE (see Planning and Use Guide ) 
resident access method area 30 
resident reenterable module area 30 
resource 

release 100 

request control 108 

request status 108 
resources 

gettin<i control of 38-4 3 

naming 39 

serially reusable 38,39 

simul tant^tHjs ii:;e o! 18,39 
f prevent in<i 19 
testi nq tor i9 
use of 38, 39 
responsibility count 31 ,32 , 35 , 36 ,60-62 
decreasing, with DELETE 99 
increasing, with IX)AD 132 
with LINK 29 ,30 
with XCTL 33, 34 
RESTORE (see Plann ing and Use Guid e) 
RETURN 137 

use of 23, 24 
return code 7,8 

rname operand of ENg, use of 39 
rout inq codes 72 - 
routiriq ires,:;ugos 197,198 
KX-tytx' 79 
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oa vt.' a r t.vi ^ , 6 ,'f , IM\ 

chaining 6,7 

with l-.TXH 0{n'r<in<l H^) 

with t'REENAIN 113 

for general registers 6,138 

with Gl-JTMAIN 117 

with LINK 2'),.)0 

[)roviding 6 

with SAVM I.IH 

wit h STIMEH 1 S 1 

with XCTL 17 0 
security message routiiKj 71,197 
segment overlay tt i 
segiuen t , V;;^ H 
:;i':c;wi' i 

seiial execution IH 

serially reusable iiiotJule JO, .iJ 

services, summary ot 1 

set interval tjiiu r (STIMI-R) ISl 

shared re(iuests 4 0 

shared subpools ')7 

signal event coiripietion (PO.'JT) 136 
siniple structure 17 
SMB (system message t)icck) 73 
SMFWTM (see Pla nning and Use G uide) 
SNAP 140-144 

dunii 50,51 

execute form 144 

list form 143 

stanii.ird form 140-14 2 
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Your views about this publication may help improve its usefulness; this form 
will be sent to the author's department for appropriate action. Using this 
form to request system assistance or additional publications will delay response, 
however. For more direct handling of such requests, please contact your 
IBM representative or the IBM Branch Office serving your locality. 

How did you use this publication? 

□ As an introduction □ As a text (student) 

□ As a reference manual □ As a text (instructor) 

□ For another purpose (explain) 



Please comment on the general usefulness of the book; suggest additions, deletions, and clarifications; list 
specific errors and omissions (give page numbers): 



What is your occupation? 

Number of latest Technical Newsletter (if any) concerning this publication: _ 
Please Include your name and address in the space below if you wish a reply. 



Thank you for your cooperation. No postage stamp necessary if mailed in the U.S.A. (Elsewhere, an IBM office 
or representative will be happy to forward your comments.) 
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programmers, and operators of IBM systems. Yout comments on the other side of this 
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this material. All comments and svigge&tions become tihte property of IBM. 
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